@stigmer/server 3.14.0-dev.20260910084630

package/src/domain/schedule/steps.ts

@@ -0,0 +1,281 @@
+/**
+ * Schedule write-path steps — ports the validation half of
+ * pkg/domain/schedule/controller/steps.go: the defaults resolver
+ * (create/apply) and the update validator, plus the workspace and
+ * model-pinning rules both share.
+ *
+ * Proven by schedule.conformance.test.ts (CONFORMANCE_TARGET=local) and
+ * __tests__/schedule.composed.test.ts.
+ */
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+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 type { ScheduleSpec } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/spec_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import {
+  failedPreconditionError,
+  internalError,
+  invalidArgumentError,
+  notFoundError,
+} from "../../pipeline/errors.js";
+import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { RequestContext } from "../../pipeline/request-context.js";
+import { findResourceBySlug } from "../../pipeline/steps/helpers.js";
+import { EXISTING_RESOURCE_KEY } from "../../pipeline/steps/load-existing.js";
+import type { Store } from "../../store/interface.js";
+import { scheduleModelPinningRefusal } from "../../temporal/schedule/model-pinning.js";
+import {
+  harnessName,
+  unknownModelPinRefusal,
+} from "../workflow/registry/pin-validation.js";
+import type { ModelCatalogProvider } from "../workflow/registry/model-catalog-provider.js";
+import { validateScheduleCron, validateScheduleTimeZone } from "./cron.js";
+
+export interface ScheduleValidationDeps {
+  readonly store: Store;
+  readonly modelRegistry: ModelCatalogProvider;
+}
+
+/**
+ * Prepares a schedule for creation — the ScheduleDefaultsResolver mirror
+ * (cloud edition), whose error contracts this step replicates
+ * byte-identically (Go resolveScheduleDefaultsStep):
+ *
+ *  1. Requires metadata.org — the schedule-owning org is the billing org
+ *     for every fire (DD-008 D4), so it can never be inferred.
+ *  2. Validates the cron grammar and the time zone (cron.ts — the DD-009
+ *     C-4 lexical rules; no cron parsing in either edition).
+ *  3. Requires spec.agent.agent_ref.slug and normalizes its org (empty
+ *     means same-org, the platform-wide relative-reference convention).
+ *  4. Enforces the same-org invariant: agent_ref.org must equal
+ *     metadata.org — the schedule's org pays for every fire, and both must
+ *     be the agent's. Checked BEFORE the agent load so a cross-org request
+ *     cannot probe another org's slugs through this path.
+ *  5. Loads the referenced agent — scheduling a nonexistent agent is
+ *     refused with the same NOT_FOUND a direct agent lookup would produce.
+ *
+ * Deliberately NO slug default from the agent: schedules are N-per-agent
+ * with different prompts, so no single schedule is "the" canonical one. A
+ * schedule without a slug or name falls through to the generic ResolveSlug
+ * derive-from-name behavior.
+ *
+ * Resolution is idempotent: an already-resolved schedule passes through
+ * unchanged, so the apply pipeline running it before delegating to the
+ * create pipeline (which runs it again) is harmless.
+ */
+export function newResolveScheduleDefaultsStep(
+  deps: ScheduleValidationDeps,
+): PipelineStep<typeof ScheduleSchema> {
+  return {
+    name: "ResolveScheduleDefaults",
+    async execute(ctx: RequestContext<typeof ScheduleSchema>): Promise<void> {
+      const schedule = ctx.newState;
+      const metadata = schedule.metadata;
+
+      if ((metadata?.org ?? "") === "") {
+        throw invalidArgumentError("metadata.org is required for a schedule");
+      }
+
+      const spec = schedule.spec;
+      validateScheduleCron(spec?.cron ?? "");
+      validateScheduleTimeZone(spec?.timeZone ?? "");
+
+      const agentRef =
+        spec?.target.case === "agent" ? spec.target.value.agentRef : undefined;
+      if ((agentRef?.slug ?? "") === "") {
+        throw invalidArgumentError("spec.agent.agent_ref.slug is required");
+      }
+
+      validateScheduleWorkspace(spec);
+      validateScheduleModelPinning(deps.modelRegistry, spec);
+
+      // Empty ref org means same-org; make it absolute before the
+      // invariant compares orgs.
+      let refOrg = agentRef?.org ?? "";
+      if (refOrg === "") {
+        refOrg = metadata?.org ?? "";
+      }
+
+      // The same-org invariant (spec.proto): the schedule's org is the
+      // billing org for every fire, and it must be the agent's. Checked
+      // BEFORE the agent load so a cross-org request cannot probe another
+      // org's slugs through this path.
+      if (refOrg !== (metadata?.org ?? "")) {
+        throw failedPreconditionError(
+          `spec.agent.agent_ref.org must match metadata.org — a schedule must live in the referenced agent's organization (${refOrg})`,
+        );
+      }
+
+      let found;
+      try {
+        found = await findResourceBySlug(
+          deps.store,
+          ApiResourceKind.agent,
+          AgentSchema,
+          agentRef?.slug ?? "",
+          refOrg,
+        );
+      } catch (error) {
+        throw internalError(error, "failed to list agent resources");
+      }
+      if (found === undefined) {
+        // Byte-identical with the direct agent lookup's refusal (the T09
+        // indistinguishability contract).
+        throw notFoundError("Agent", agentRef?.slug ?? "");
+      }
+
+      if (agentRef !== undefined) {
+        agentRef.org = refOrg;
+      }
+    },
+  };
+}
+
+/**
+ * Enforces the schedule-specific workspace constraint on the shared
+ * AgentInvocation (DD-018 D-3): every workspace entry must be a git_repo
+ * source. A local_path needs a connected client to serve the directory,
+ * and a schedule fire has none — refusing at write time beats a
+ * deterministic provisioning failure at 3 AM. Copy is cross-edition
+ * contract (Go validateScheduleWorkspace).
+ */
+export function validateScheduleWorkspace(spec: ScheduleSpec | undefined): void {
+  const entries =
+    spec?.target.case === "agent" ? spec.target.value.workspaceEntries : [];
+  for (const [i, entry] of entries.entries()) {
+    if (entry.source?.source.case !== "gitRepo") {
+      throw invalidArgumentError(
+        `spec.agent.workspace_entries[${i}] must use a git_repo source — a scheduled run has no connected client to serve a local_path`,
+      );
+    }
+  }
+}
+
+/**
+ * Enforces the two unattended model-pinning rules at write time (Go
+ * validateScheduleModelPinning):
+ *
+ *   - PRESENCE (stigmer/stigmer#362): a Cursor-harness schedule must pin a
+ *     model. Stated once in the clock's scheduleModelPinningRefusal, which
+ *     the run starter also evaluates as the launch backstop for rows
+ *     written before the rule existed.
+ *   - EXISTENCE (stigmer/stigmer#774): whatever model IS pinned must be in
+ *     the registry for the harness the fires would use — a typo'd pin used
+ *     to pass through verbatim and silently run (and bill) as Auto.
+ *     Write-time only BY DESIGN (no fire-time backstop — registry drift
+ *     must never break an existing schedule at its 3 AM fire).
+ */
+export function validateScheduleModelPinning(
+  modelRegistry: ModelCatalogProvider,
+  spec: ScheduleSpec | undefined,
+): void {
+  const presence = scheduleModelPinningRefusal(spec);
+  if (presence !== "") {
+    throw invalidArgumentError(presence);
+  }
+  const invocation = spec?.target.case === "agent" ? spec.target.value : undefined;
+  const existence = unknownModelPinRefusal(
+    modelRegistry,
+    "spec.agent.run_config.model_name",
+    harnessName(invocation?.harness ?? 0),
+    invocation?.runConfig?.modelName ?? "",
+  );
+  if (existence !== "") {
+    throw invalidArgumentError(existence);
+  }
+}
+
+/**
+ * The manifest vocabulary for the schedule's target arm — the populated
+ * target-oneof member's field name, exactly what users declared in YAML
+ * (Go targetFieldName resolves it through proto reflection; connect-es
+ * exposes the case name directly, identical for the single-word fields
+ * this oneof carries — "agent" today, "workflow" reserved).
+ */
+export function targetFieldName(spec: ScheduleSpec | undefined): string {
+  return spec?.target.case ?? "";
+}
+
+/**
+ * Enforces the schedule's immutable identity on update (Go
+ * validateScheduleUpdateStep):
+ *
+ *   - spec.agent.agent_ref must keep referencing the same agent. Create's
+ *     consent bar is can_edit on the REFERENCED agent (cloud edition); if
+ *     an update could repoint the target, a schedule owner could drive an
+ *     agent they may not edit — bypassing that consent. Create a new
+ *     schedule instead (nothing is lost — a schedule carries no install
+ *     state).
+ *   - The target arm (target oneof case) must not change. An agent
+ *     schedule must not morph into a workflow schedule — the two targets
+ *     enter different execution pipelines. Trivially satisfied while one
+ *     arm exists; enforced structurally so the workflow arm lands with the
+ *     rule already in force.
+ *   - The cron grammar and time zone are re-validated: update replaces the
+ *     spec wholesale and does not run the defaults resolver, so the write
+ *     path must hold the same bar as create.
+ *
+ * Runs after LoadExisting. metadata.slug/org immutability needs no step
+ * here: the generic BuildUpdateState preserves both from the existing
+ * resource. Status (firing observations, auto-pause) is likewise preserved
+ * wholesale — the invariant that keeps DD-008 D7's auto-pause immune to
+ * declarative clobber.
+ */
+export function newValidateScheduleUpdateStep(
+  deps: ScheduleValidationDeps,
+): PipelineStep<typeof ScheduleSchema> {
+  return {
+    name: "ValidateScheduleUpdate",
+    execute(ctx: RequestContext<typeof ScheduleSchema>): void {
+      const existing = ctx.get(EXISTING_RESOURCE_KEY) as Schedule | undefined;
+      if (existing === undefined) {
+        throw internalError(
+          new Error("existing schedule not found in context"),
+          "existing schedule not found in context",
+        );
+      }
+
+      const newState = ctx.newState;
+
+      const inputTarget = targetFieldName(newState.spec);
+      const existingTarget = targetFieldName(existing.spec);
+      if (inputTarget !== existingTarget) {
+        throw failedPreconditionError(
+          `spec target is immutable (schedule target is ${existingTarget}) — create a new schedule for a different target kind`,
+        );
+      }
+
+      const spec = newState.spec;
+      validateScheduleCron(spec?.cron ?? "");
+      validateScheduleTimeZone(spec?.timeZone ?? "");
+      // Update replaces the spec wholesale (no defaults resolver), so the
+      // workspace and model-pinning constraints must hold here too.
+      validateScheduleWorkspace(spec);
+      validateScheduleModelPinning(deps.modelRegistry, spec);
+
+      const inputRef =
+        spec?.target.case === "agent" ? spec.target.value.agentRef : undefined;
+      const existingRef =
+        existing.spec?.target.case === "agent"
+          ? existing.spec.target.value.agentRef
+          : undefined;
+
+      // Normalize the input ref's org the same way create does (empty
+      // means the schedule's own org) before comparing.
+      let inputOrg = inputRef?.org ?? "";
+      if (inputOrg === "") {
+        inputOrg = existing.metadata?.org ?? "";
+      }
+
+      if (
+        (inputRef?.slug ?? "") !== (existingRef?.slug ?? "") ||
+        inputOrg !== (existingRef?.org ?? "")
+      ) {
+        throw failedPreconditionError(
+          `spec.agent.agent_ref is immutable (schedule runs ${existingRef?.org ?? ""}/${existingRef?.slug ?? ""}) — create a new schedule to run a different agent`,
+        );
+      }
+    },
+  };
+}

package/src/domain/schedule/trigger.ts

@@ -0,0 +1,283 @@
+/**
+ * The trigger command's steps — ports
+ * pkg/domain/schedule/controller/trigger.go (DD-017 D-5/D-6, amending
+ * DD-014).
+ *
+ * The manual fire runs SYNCHRONOUSLY through the standard execution create
+ * pipeline — every launch gate runs — and the result names what happened:
+ * the created execution's id, or the refusing gate's copy verbatim.
+ * Two-level contract: a gRPC error means the trigger itself was refused
+ * (missing → NOT_FOUND, disabled → FAILED_PRECONDITION); a gRPC success
+ * means the fire happened, whatever the run's outcome — a deterministically
+ * refused run is a successful trigger honestly reported, never an
+ * exception.
+ *
+ * Semantics settled by DD-017 D-5:
+ *   - A PAUSED schedule may be triggered (test-then-resume): a test fire
+ *     is exactly how an owner verifies a fix before resuming, and resume
+ *     stays the one path that clears the latch.
+ *   - Manual fires do NOT feed the failure streak: the sync path is
+ *     untracked (the caller watches the execution), so it has no honest
+ *     completion verdict to contribute — and a test fire of a broken
+ *     schedule must not race its owner to the pause threshold.
+ *   - The handler stamps last_fire_at and writes the fire-ledger row
+ *     (origin=manual) because the tick is not in the path to do it; the
+ *     run starter stamps last_execution_id on success as it does for cron
+ *     fires.
+ */
+import { create } from "@bufbuild/protobuf";
+import type { DescMessage } from "@bufbuild/protobuf";
+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 {
+  ScheduleRunOutcome,
+  ScheduleTriggerResultSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/io_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 { ConnectError } from "@connectrpc/connect";
+
+import type { Logger } from "../../boot/logger.js";
+import type { CallerIdentity } from "../../extensions/identity.js";
+import {
+  failedPreconditionError,
+  rethrownStatusError,
+} 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";
+import { recordManualFire } from "../../temporal/schedule/run-ledger.js";
+import { rfc3339Seconds } from "../../temporal/schedule/run-ledger.js";
+import type { RunOutcomeResult } from "../../temporal/schedule/run-starter.js";
+
+// The trigger refusal copy, byte-identical to the cloud edition's
+// ScheduleTriggerHandler (same error contracts in both editions; the
+// conformance suite asserts these verbatim). A change on either side must
+// change both.
+
+/**
+ * The owner's switch is off. OSS has no blueprint-access layer, so the
+ * refusal here is pure contract parity: cloud MUST refuse (a
+ * disabled-schedule run would die mid-execution after billing side
+ * effects, DD-017 D-5), and the two editions must not diverge on a refusal
+ * a user can observe. Consoles turn the dead end into a one-click
+ * "Enable & run now".
+ */
+export const TRIGGER_DISABLED_MESSAGE =
+  "schedule is disabled (spec.enabled=false) — enable it before triggering";
+
+/**
+ * No run starter is wired into this process (production wiring always
+ * injects it — this is the defensive posture for embedded/test assemblies
+ * that skip server wiring): refuse honestly, never pretend.
+ */
+export const TRIGGER_NO_RUNNER_MESSAGE =
+  "this Stigmer server process has no schedule run starter wired — the schedule cannot fire";
+
+/**
+ * The narrow slice of the scheduling runtime the trigger needs (satisfied
+ * by the clock's RunStarter): start one run through the full execution
+ * create pipeline and answer with the real outcome. Deliberately NOT the
+ * Clock — a manual fire needs no Temporal artifact (DD-017 D-5 amending
+ * DD-014 D-A): the artifact round-trip made the fire asynchronous, so the
+ * RPC answered "started" before the launch gates ran — exactly the false
+ * toast the owner hit (Go Runner).
+ */
+export interface ScheduleRunner {
+  startRun(
+    schedule: Schedule,
+    nominalFireTime: Date,
+  ): Promise<RunOutcomeResult>;
+}
+
+/** A provider so the compose root can wire the runner after the clock stage. */
+export type RunnerProvider = () => ScheduleRunner | undefined;
+
+/** Carries the shaped ScheduleTriggerResult from the fire step to the handler. */
+export const TRIGGER_RESULT_KEY = "trigger_result";
+
+/**
+ * Refuses a disabled schedule (the owner's switch) — the ONE remaining
+ * trigger refusal (DD-017 D-5 narrowed DD-014 D-B's matrix: paused
+ * schedules are now triggerable, and the tick's revalidation no longer
+ * guards manual fires because manual fires no longer pass through the
+ * tick). Go validateTriggerableStep.
+ */
+export function newValidateTriggerableStep<
+  Desc extends DescMessage,
+>(): PipelineStep<Desc> {
+  return {
+    name: "ValidateTriggerable",
+    execute(ctx: RequestContext<Desc>): void {
+      const schedule = ctx.get(EXISTING_RESOURCE_KEY) as Schedule;
+      if (!(schedule.spec?.enabled ?? false)) {
+        throw failedPreconditionError(TRIGGER_DISABLED_MESSAGE);
+      }
+    },
+  };
+}
+
+export interface FireDirectRunDeps {
+  readonly store: Store;
+  readonly runner: RunnerProvider;
+  readonly logger: Logger;
+}
+
+/**
+ * Starts the run in-process and shapes the result: stamp last_fire_at, run
+ * the full create pipeline via the Runner, write the fire-ledger row,
+ * mirror the outcome into ScheduleTriggerResult. Infrastructure failures
+ * from the create pipeline propagate as the handler's error — the
+ * in-process client already speaks gRPC status (Go fireDirectRunStep).
+ */
+export function newFireDirectRunStep<Desc extends DescMessage>(
+  deps: FireDirectRunDeps,
+): PipelineStep<Desc> {
+  return {
+    name: "FireDirectRun",
+    async execute(ctx: RequestContext<Desc>): Promise<void> {
+      const runner = deps.runner();
+      if (runner === undefined) {
+        throw failedPreconditionError(TRIGGER_NO_RUNNER_MESSAGE);
+      }
+
+      const schedule = ctx.get(EXISTING_RESOURCE_KEY) as Schedule;
+      const scheduleId = schedule.metadata?.id ?? "";
+
+      // The manual fire's nominal time is the trigger instant, whole
+      // seconds — the same identity the deterministic execution name uses,
+      // so a manual fire at the exact cron nominal second converges on the
+      // same execution via the ALREADY_EXISTS → re-find path.
+      const nominal = new Date(Math.floor(Date.now() / 1000) * 1000);
+      const nominalRfc3339 = rfc3339Seconds(nominal);
+
+      let outcome: RunOutcomeResult;
+      try {
+        outcome = await runner.startRun(schedule, nominal);
+      } catch (error) {
+        deps.logger.warn(
+          "Manual trigger's run start failed on infrastructure",
+          {
+            schedule_id: scheduleId,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        );
+        // The in-process client's error instance carries the INNER
+        // response's metadata; echoing it corrupts the serving HTTP/2
+        // trailers (NGHTTP2_PROTOCOL_ERROR — the #18 transport finding).
+        // Re-mint code + message, exactly the workflowexecution
+        // forwarding posture.
+        throw error instanceof ConnectError
+          ? rethrownStatusError(error)
+          : error;
+      }
+
+      // The fire happened: record it — last_fire_at on status (the tick is
+      // not in this path to do it) and the ledger row (origin=manual).
+      await stampLastFireAt(deps, scheduleId, nominal, ctx.callerIdentity);
+      await recordManualFire(
+        deps.store,
+        deps.logger,
+        scheduleId,
+        schedule.metadata?.org ?? "",
+        nominalRfc3339,
+        outcome,
+      );
+
+      const result = create(ScheduleTriggerResultSchema);
+      switch (outcome.kind) {
+        case "started":
+          result.outcome = ScheduleRunOutcome.STARTED;
+          result.executionId = outcome.executionId;
+          deps.logger.info("Schedule triggered manually — run started", {
+            schedule_id: scheduleId,
+            execution_id: outcome.executionId,
+            already_existed: outcome.alreadyExisted,
+          });
+          break;
+        case "targetMissing":
+          result.outcome = ScheduleRunOutcome.TARGET_MISSING;
+          result.refusalReason = outcome.reason;
+          deps.logger.warn("Schedule triggered manually — target missing", {
+            schedule_id: scheduleId,
+            reason: outcome.reason,
+          });
+          break;
+        case "refused":
+          result.outcome = ScheduleRunOutcome.REFUSED;
+          result.refusalReason = outcome.reason;
+          deps.logger.warn(
+            "Schedule triggered manually — run refused by a launch gate",
+            { schedule_id: scheduleId, reason: outcome.reason },
+          );
+          break;
+        default: {
+          const exhaustive: never = outcome;
+          throw new Error(`unknown run outcome ${String(exhaustive)}`);
+        }
+      }
+
+      // Answer with the post-fire row — last_fire_at and (on success)
+      // last_execution_id freshly stamped. A failed re-read degrades to the
+      // loaded schedule rather than failing a fire that already happened.
+      try {
+        result.schedule = await deps.store.getResource(
+          ApiResourceKind.schedule,
+          scheduleId,
+          ScheduleSchema,
+        );
+      } catch {
+        result.schedule = schedule;
+      }
+
+      ctx.set(TRIGGER_RESULT_KEY, result);
+    },
+  };
+}
+
+/**
+ * Records the manual fire on status — best-effort with a loud log: the run
+ * already started, and a bookkeeping failure must not turn a real fire
+ * into a caller-visible error. (The cron path's stamp rides the tick's
+ * recordFire; this is its manual twin. Uses the FULL shared audit helper —
+ * this is a request-path write, unlike the clock's minimal bump.) Go
+ * stampLastFireAt.
+ */
+async function stampLastFireAt(
+  deps: FireDirectRunDeps,
+  scheduleId: string,
+  nominal: Date,
+  identity: CallerIdentity,
+): Promise<void> {
+  try {
+    await deps.store.updateResource(
+      ApiResourceKind.schedule,
+      scheduleId,
+      ScheduleSchema,
+      (live) => {
+        if (live.status === undefined) {
+          live.status = create(ScheduleStatusSchema);
+        }
+        live.status.lastFireAt = timestampFromDate(nominal);
+        setAuditFieldsForUpdate(ScheduleSchema, live, "status_audit", identity);
+      },
+    );
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      return;
+    }
+    deps.logger.warn(
+      "Manual fire's last_fire_at not stamped (best-effort — the run is unaffected)",
+      {
+        schedule_id: scheduleId,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    );
+  }
+}