@intentius/chant 0.49.0 → 0.51.0

package/src/lint/rules/comp/comp.test.ts

@@ -23,11 +23,14 @@ const checks = loadComponentChecks();
 /**
  * Rollback dispositions the COMP003 fixtures reference, standing in for what
  * `chant lint` derives from the project's registry (`cfn-deploy` has a native
- * `rollback`; `run-migration` declares `needs-opt-out` in the aws lexicon).
+ * `rollback`; `run-migration` declares `needs-opt-out` in the aws lexicon;
+ * `run-agent` declares `native` from phase 1 (#1941) — see
+ * `../../../components/verbs/run-agent.ts`'s `rollbackPolicy: "native"`).
  */
 const FIXTURE_ROLLBACK_POLICIES = new Map<string, RollbackPolicy>([
   ["cfn-deploy", "native"],
   ["run-migration", "needs-opt-out"],
+  ["run-agent", "native"],
 ]);
 
 async function lintFixture(
@@ -124,6 +127,16 @@ describe("COMP003: mutating-no-rollback", () => {
     expect(diagnostics.filter((d) => d.checkId === "COMP003")).toHaveLength(0);
   });
 
+  it("does not flag a bare run-agent step — its registry-declared rollbackPolicy is \"native\" (#1941), never needing a noRollback opt-out (#1944)", async () => {
+    // Regression test: proves the registry's rollbackPolicy for "run-agent"
+    // is wired correctly into ctx.rollbackPolicies (the same seam COMP005
+    // uses for ctx.knownKinds), not just that COMP003 happens to stay quiet.
+    // See ../../../components/verbs/run-agent.ts's "rollbackPolicy: 'native'".
+    const diagnostics = await lintFixture("comp003", "pass", { rollbackPolicies: FIXTURE_ROLLBACK_POLICIES });
+    const hits = diagnostics.filter((d) => d.checkId === "COMP003" && d.component === "agent-turn");
+    expect(hits).toHaveLength(0);
+  });
+
   it("flags a needs-opt-out step nested inside a fan-out phase, not just top-level phases", () => {
     // Regression test: the rule used to iterate component.deploy directly and
     // never recursed into nested Phase entries (a fan-out unit, e.g. the
@@ -163,6 +176,41 @@ describe("COMP003: mutating-no-rollback", () => {
     expect(diagnostics[0].message).toContain("run-migration");
   });
 
+  it("DOES flag a \"run-agent\"-kind step when a synthetic registry declares it needs-opt-out — proves the rule is conditional on the registry, not a hard-coded allowance for this one verb name (#1944)", () => {
+    // Companion negative case to the "does not flag a bare run-agent step"
+    // test above: same step kind, same shape, but with a synthetic
+    // rollbackPolicies map that declares "run-agent" as "needs-opt-out"
+    // instead of the real registry's "native". If this rule silently
+    // special-cased "run-agent" by name, this would incorrectly pass; it must
+    // flag exactly like any other needs-opt-out verb.
+    const [comp003] = checks.filter((c) => c.id === "COMP003");
+    const ctx = {
+      rollbackPolicies: new Map<string, RollbackPolicy>([["run-agent", "needs-opt-out"]]),
+      components: new Map([
+        [
+          "agent-turn",
+          {
+            component: {
+              name: "agent-turn",
+              dependsOn: [],
+              deploy: [
+                {
+                  phase: "Run",
+                  steps: [{ kind: "run-agent", agent: "claude", task: { prompt: "..." }, workspace: {} }],
+                },
+              ],
+            },
+            filePath: "agent-turn.component.ts",
+          },
+        ],
+      ]),
+    };
+    const diagnostics = comp003.check(ctx as never);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].component).toBe("agent-turn");
+    expect(diagnostics[0].message).toContain("run-agent");
+  });
+
   it("a compensation sibling only counts within the same nested phase, not a same-named sibling phase elsewhere in the component", () => {
     // Two different "Node" phases both contain a run-migration step; only the
     // second one has a rollback-previous sibling. The first must still be

package/src/lint/rules/evl001-non-literal-expression.test.ts

@@ -90,11 +90,16 @@ describe("EVL001: non-literal-expression", () => {
     expect(diags[0].message).toContain("statically evaluable");
   });
 
-  test("flags method call", () => {
+  // chant #1966 — `fold()` widened to fold a method call when its receiver
+  // resolves (`github.actor.toString()`, `[...].join(",")`); `findSubsetViolation`
+  // (./subset.ts) accepts the SHAPE unconditionally, the same way it already
+  // does for `.step` and a nested `new` — whether the receiver actually
+  // resolves is resolution-dependent and out of reach here, so a method call
+  // no longer trips this rule on shape alone.
+  test("does not flag a method call — resolution-dependent, out of scope for a syntax-only rule (chant #1966)", () => {
     const ctx = createContext(`new Bucket({ name: config.getName() });`);
     const diags = evl001NonLiteralExpressionRule.check(ctx);
-    expect(diags).toHaveLength(1);
-    expect(diags[0].ruleId).toBe("EVL001");
+    expect(diags).toHaveLength(0);
   });
 
   test("flags await expression", () => {

package/src/lint/rules/evl001-non-literal-expression.ts

@@ -31,14 +31,14 @@ function checkNode(node: ts.Node, context: LintContext, diagnostics: LintDiagnos
       const firstArg = node.arguments[0];
       if (ts.isObjectLiteralExpression(firstArg)) {
         for (const prop of firstArg.properties) {
-          // chant #1544 — `allowCompositeStepAccess: true` opts EVL001 (and
-          // only EVL001; `fold()` never sets this) into treating
           // `Checkout({...}).step` — the single-action Composite()-wrapper
           // idiom every lexicon's own docs/examples embed inline inside a
-          // Job's `steps:` array — as shape-valid. See findSubsetViolation's
-          // doc comment (../../fold/subset.ts) for why this is a documented,
-          // EVL-only, more-permissive divergence rather than a shared one.
-          const violation = checkObjectMember(prop, context.intrinsics, true);
+          // Job's `steps:` array — is shape-valid unconditionally (chant
+          // #1544 introduced this as an EVL-only opt-in while `fold()`
+          // still rejected the shape; chant #1174 closed that divergence by
+          // making `fold()` accept it too, so `findSubsetViolation` no
+          // longer needs a flag to say so).
+          const violation = checkObjectMember(prop, context.intrinsics);
           if (violation) {
             const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
               violation.node.getStart(context.sourceFile),

package/src/lsp/lexicon-providers.test.ts

@@ -53,3 +53,47 @@ describe("lexiconCompletions resource ranking (#600)", () => {
     expect(items.length).toBe(100);
   });
 });
+
+describe("lexiconCompletions deprecation marking (#1701)", () => {
+  /** One resource with a declared deprecation and an inferred one. */
+  function bucketIndex(): LexiconIndex {
+    return new LexiconIndex({
+      Bucket: {
+        resourceType: "Test::S3::Bucket",
+        kind: "resource",
+        lexicon: "test",
+        createOnly: ["AccessControl", "Runtime", "BucketName"],
+        deprecatedProperties: ["AccessControl", "Runtime"],
+        inferredDeprecations: ["Runtime"],
+      },
+    });
+  }
+
+  const propCtx = (): CompletionContext =>
+    ({
+      uri: "file:///t.ts",
+      content: "const b = new Bucket({\n  ",
+      linePrefix: "  ",
+      wordAtCursor: "",
+      position: { line: 1, character: 2 },
+    }) as unknown as CompletionContext;
+
+  test("a declared deprecation is marked deprecated", () => {
+    const items = lexiconCompletions(propCtx(), bucketIndex(), "Test resource");
+    const access = items.find((i) => i.label === "AccessControl");
+    expect(access?.deprecated).toBe(true);
+  });
+
+  test("an inferred deprecation is not marked deprecated", () => {
+    const items = lexiconCompletions(propCtx(), bucketIndex(), "Test resource");
+    const runtime = items.find((i) => i.label === "Runtime");
+    expect(runtime).toBeDefined();
+    expect(runtime?.deprecated).toBeUndefined();
+  });
+
+  test("a property with no deprecation signal is not marked", () => {
+    const items = lexiconCompletions(propCtx(), bucketIndex(), "Test resource");
+    const name = items.find((i) => i.label === "BucketName");
+    expect(name?.deprecated).toBeUndefined();
+  });
+});

package/src/lsp/lexicon-providers.ts

@@ -20,6 +20,13 @@ export interface LexiconEntry {
   writeOnly?: string[];
   primaryIdentifier?: string[];
   deprecatedProperties?: string[];
+  /**
+   * Subset of `deprecatedProperties` that only prose supports — a lexicon
+   * generator matched the property description against a deprecation regex
+   * rather than reading an upstream declaration (#1701). Editors do not strike
+   * these through; the basis is too weak to mark a property dead.
+   */
+  inferredDeprecations?: string[];
   conditionalCreateOnly?: string[];
   replacementStrategy?: "delete_then_create" | "create_then_delete";
   tagging?: { taggable: boolean; tagOnCreate: boolean; tagUpdatable: boolean };
@@ -127,7 +134,10 @@ export function lexiconCompletions(
     const entry = index.getEntry(className);
     const props = index.getPropertyNames(className);
     if (props.length > 0) {
-      const deprecatedSet = new Set(entry?.deprecatedProperties ?? []);
+      const inferred = new Set(entry?.inferredDeprecations ?? []);
+      const deprecatedSet = new Set(
+        (entry?.deprecatedProperties ?? []).filter((p) => !inferred.has(p)),
+      );
       const filtered = wordAtCursor
         ? props.filter((p) => p.toLowerCase().startsWith(wordAtCursor.toLowerCase()))
         : props;

package/src/op/activity-contract.test.ts

@@ -0,0 +1,180 @@
+/**
+ * Activity contract tests (chant #1288 Stage 1).
+ *
+ * Exercises the four failure classes named in the issue, using a small
+ * lifecycleDiff-shaped contract so the test doesn't need a real lexicon.
+ */
+
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { activity, phase, effect } from "./builders";
+import type { OpConfig } from "./types";
+import {
+  activityContract,
+  isActivityContract,
+  collectActivityContracts,
+  validateActivitySteps,
+  type ActivityContract,
+} from "./activity-contract";
+import { stepOutput } from "./step-output-ref";
+import { EffectReceipt } from "../effect-receipt";
+
+// ── activityContract() / isActivityContract() ──────────────────────────────
+
+describe("activityContract()", () => {
+  it("brands its result so isActivityContract recognizes it", () => {
+    const contract = activityContract("noop", z.strictObject({}));
+    expect(isActivityContract(contract)).toBe(true);
+    expect(contract.name).toBe("noop");
+  });
+
+  it("isActivityContract rejects a plain object with the same shape", () => {
+    expect(isActivityContract({ name: "noop", args: z.strictObject({}) })).toBe(false);
+    expect(isActivityContract(null)).toBe(false);
+    expect(isActivityContract(undefined)).toBe(false);
+  });
+});
+
+describe("collectActivityContracts()", () => {
+  it("collects every exported contract, keyed by its declared name — ignores non-contract exports", () => {
+    const mod = {
+      shellCmdContract: activityContract("shellCmd", z.strictObject({ cmd: z.string() })),
+      httpCheckContract: activityContract("httpCheck", z.strictObject({ url: z.string() })),
+      unrelatedExport: "not a contract",
+      SOME_CONSTANT: 42,
+    };
+    const into = new Map<string, ActivityContract>();
+    collectActivityContracts(mod, into);
+    expect([...into.keys()].sort()).toEqual(["httpCheck", "shellCmd"]);
+    expect(into.get("shellCmd")!.name).toBe("shellCmd");
+  });
+});
+
+// ── validateActivitySteps() ─────────────────────────────────────────────────
+
+const lifecycleDiffContract = activityContract(
+  "lifecycleDiff",
+  z.strictObject({ env: z.string(), live: z.boolean().optional() }),
+  z.object({ output: z.string(), exitCode: z.number(), drifted: z.boolean() }),
+);
+
+const helmInstallContract = activityContract(
+  "helmInstall",
+  z.strictObject({ name: z.string(), chart: z.string().optional(), namespace: z.string().optional() }),
+);
+
+function opWith(config: Partial<OpConfig> & Pick<OpConfig, "phases">): Pick<OpConfig, "name" | "phases" | "onFailure"> {
+  return { name: "test-op", ...config };
+}
+
+describe("validateActivitySteps() — passing Ops", () => {
+  it("returns no issues for a step matching its contract exactly", () => {
+    const config = opWith({ phases: [phase("Diff", [activity("lifecycleDiff", { env: "prod", live: true })])] });
+    const issues = validateActivitySteps(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    expect(issues).toEqual([]);
+  });
+
+  it("skips a step whose fn has no registered contract — non-breaking by design", () => {
+    const config = opWith({ phases: [phase("Deploy", [activity("somethingUnregistered", { anything: "goes" })])] });
+    const issues = validateActivitySteps(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    expect(issues).toEqual([]);
+  });
+
+  it("a valid outcomeAttribute.from path against the declared return schema passes", () => {
+    const step = activity("lifecycleDiff", { env: "prod" });
+    step.outcomeAttribute = { name: "Drift", from: "drifted" };
+    const config = opWith({ phases: [phase("Diff", [step])] });
+    const issues = validateActivitySteps(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    expect(issues).toEqual([]);
+  });
+
+  it("a step-output reference standing in for a typed arg does not trip a false-positive type mismatch (#1290)", () => {
+    // args.env is z.string() — a StepOutputRef placeholder there is not a
+    // string, but it's not a real error either; TMP013 validates it against
+    // the producer's return schema separately.
+    const step = activity("lifecycleDiff", { env: stepOutput("diff", "name") as unknown as string });
+    const config = opWith({ phases: [phase("Diff", [step])] });
+    const issues = validateActivitySteps(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    expect(issues).toEqual([]);
+  });
+
+  it("a step-output reference elsewhere in args doesn't mask a genuinely unrecognized key", () => {
+    const step = activity("lifecycleDiff", { env: stepOutput("diff", "name") as unknown as string, typo: "oops" });
+    const config = opWith({ phases: [phase("Diff", [step])] });
+    const issues = validateActivitySteps(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    expect(issues.some((i) => i.message.includes("Unrecognized key") && i.message.includes("typo"))).toBe(true);
+  });
+});
+
+describe("validateActivitySteps() — the four failure classes from #1288", () => {
+  it("flags an unknown profile — e.g. kubectlApply(..., { profile: \"longInfa\" })", () => {
+    const step = activity("kubectlApply", { manifest: "dist/k8s.yaml" }, "longInfa" as never);
+    const config = opWith({ phases: [phase("Deploy", [step])] });
+    const issues = validateActivitySteps(config, new Map());
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toContain('unknown profile "longInfa"');
+    expect(issues[0].message).toContain("fastIdempotent");
+  });
+
+  it("flags an arg key the schema doesn't recognize — e.g. helmInstall(..., { nameSpace: \"prod\" })", () => {
+    const step = activity("helmInstall", { name: "api", chart: "./chart", nameSpace: "prod" });
+    const config = opWith({ phases: [phase("Deploy", [step])] });
+    const issues = validateActivitySteps(config, new Map([["helmInstall", helmInstallContract]]));
+    expect(issues.some((i) => i.message.includes("Unrecognized key") && i.message.includes("nameSpace"))).toBe(true);
+  });
+
+  it("flags a wrong/missing arg key — e.g. activity(\"lifecycleDiff\", { environment: \"prod\" })", () => {
+    const step = activity("lifecycleDiff", { environment: "prod" });
+    const config = opWith({ phases: [phase("Diff", [step])] });
+    const issues = validateActivitySteps(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    // `env` (required) is missing, and `environment` is an unrecognized key.
+    expect(issues.some((i) => i.message.includes("args.env"))).toBe(true);
+    expect(issues.some((i) => i.message.includes("Unrecognized key") && i.message.includes("environment"))).toBe(true);
+  });
+
+  it("flags an outcomeAttribute.from path that doesn't exist on the declared return type", () => {
+    const step = activity("lifecycleDiff", { env: "prod" });
+    step.outcomeAttribute = { name: "Drift", from: "drifed" }; // typo: drifted
+    const config = opWith({ phases: [phase("Diff", [step])] });
+    const issues = validateActivitySteps(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    expect(issues.some((i) => i.message.includes('outcomeAttribute.from "drifed"'))).toBe(true);
+  });
+
+  it("flags a wrong-typed arg value even when the key is right", () => {
+    const step = activity("lifecycleDiff", { env: 42 as unknown as string });
+    const config = opWith({ phases: [phase("Diff", [step])] });
+    const issues = validateActivitySteps(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    expect(issues.some((i) => i.message.includes("args.env"))).toBe(true);
+  });
+});
+
+describe("validateActivitySteps() — structural coverage", () => {
+  it("walks onFailure phases too", () => {
+    const step = activity("lifecycleDiff", { environment: "prod" });
+    const config = opWith({ phases: [], onFailure: [phase("Rollback", [step])] });
+    const issues = validateActivitySteps(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    expect(issues.length).toBeGreaterThan(0);
+  });
+
+  it("walks activity steps nested inside an effect step", () => {
+    const receipt = EffectReceipt("seeded", {
+      effect: "db-seed",
+      flavor: "hash",
+      inputs: { file: "seed.sql", version: 3 },
+    });
+    const badStep = activity("lifecycleDiff", { environment: "prod" });
+    const effectStep = effect(receipt, [badStep]);
+    const config = opWith({ phases: [phase("Seed", [effectStep])] });
+    const issues = validateActivitySteps(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    expect(issues.length).toBeGreaterThan(0);
+  });
+
+  it("reports every issue across multiple steps, not just the first", () => {
+    const step1 = activity("lifecycleDiff", { environment: "prod" });
+    const step2 = activity("kubectlApply", {}, "longInfa" as never);
+    const config = opWith({ phases: [phase("P", [step1, step2])] });
+    const issues = validateActivitySteps(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    expect(issues.some((i) => i.fn === "lifecycleDiff")).toBe(true);
+    expect(issues.some((i) => i.fn === "kubectlApply")).toBe(true);
+  });
+});

package/src/op/activity-contract.ts

@@ -0,0 +1,278 @@
+/**
+ * Activity contracts — the Stage 1 fix for chant #1288 ("Ops are the one
+ * place chant accepts untyped arguments and resolves names at runtime").
+ *
+ * Maintainer decision (#1288, 2026-08-25): a staged approach. Stage 1 (this
+ * module) is registered args/return schemas per activity, validated by
+ * `chant build` against every step — non-breaking, no change to
+ * {@link ActivityStep.args}'s `Record<string, unknown>` shape or the step
+ * builders. Stage 2 (a separate PR) regenerates the step builders as fully
+ * typed wrappers for editor completion and go-to-definition. #1289 (op.json
+ * IR) and #1290 (step-output references) build on these contracts — #1290
+ * specifically needs a declared `returns` schema to validate a later step's
+ * reference into an earlier one's output against, which is why `returns` is
+ * part of the shape here even though nothing in Stage 1 reads it for that.
+ *
+ * An activity declares a contract alongside its implementation — the same
+ * "registration surface" the issue asked for (`activity-registry.ts`'s
+ * `collectActivities` already does this for implementations; this is the
+ * schema-shaped sibling). `chant build` — via a lexicon's own post-synth
+ * check, e.g. the temporal lexicon's TMP012 — resolves each step's `fn`
+ * against a contract map built the same way and validates `args` and
+ * `outcomeAttribute.from`. A step whose `fn` has no registered contract is
+ * skipped (not an error): this is deliberately incremental — a lexicon opts
+ * an activity in by declaring a contract for it, and the k8s/aws/azure/gcp/
+ * fly activity sets are expected to pick this up lexicon by lexicon rather
+ * than all at once (see the issue's "worth checking this lands cleanly"
+ * note).
+ *
+ * Ownership is decentralized on purpose: each lexicon declares contracts for
+ * the activities it implements and validates them with its own post-synth
+ * check (the same `rulePrefix`-per-lexicon pattern every other check in
+ * chant already uses), rather than a shared cross-lexicon registry. A
+ * `Temporal::Op` step can call an activity contributed by any lexicon, and
+ * `PostSynthContext.entities` already carries the whole resolved graph to
+ * every lexicon's checks, so no new plumbing is needed for that to work.
+ */
+
+import { z } from "zod";
+import type { OpConfig, PhaseDefinition, ActivityStep, StepDefinition } from "./types";
+
+/** Every literal value {@link ActivityStep.profile} may hold. Kept in sync with `types.ts`'s `ActivityStep["profile"]`. */
+export const KNOWN_ACTIVITY_PROFILES = [
+  "fastIdempotent",
+  "longInfra",
+  "k8sWait",
+  "humanGate",
+  "argoSync",
+  "policyCheck",
+] as const;
+
+const CONTRACT_BRAND = Symbol.for("chant.op.activityContract");
+
+/**
+ * A registered activity's args/return schemas — the declaration that lets
+ * `chant build` catch a typo'd or mistyped step before it ever reaches a
+ * cluster.
+ *
+ * Author `args` with `z.strictObject(...)` (or an equivalent that rejects
+ * unrecognized keys), not `z.object(...)`. Zod's default `.object()` silently
+ * drops a key it doesn't recognize instead of failing — exactly the
+ * `helmInstall("api", "./chart", { nameSpace: "prod" })` failure class the
+ * issue names, where the misspelled key vanishes instead of erroring. A
+ * strict schema turns that into a build error.
+ */
+export interface ActivityContract<Args = unknown, Return = unknown> {
+  readonly [CONTRACT_BRAND]: true;
+  /** The activity's registered name — must match a step's `fn`. */
+  name: string;
+  /** Schema every step's `args` (defaulted to `{}` when omitted) must satisfy. */
+  args: z.ZodType<Args>;
+  /**
+   * Schema the activity resolves to. Optional: an activity that returns
+   * nothing meaningful (or hasn't had its return type written down yet) can
+   * omit it. Needed to validate a step's `outcomeAttribute.from` path, and —
+   * per #1290 — a later step's reference into this one's output.
+   */
+  returns?: z.ZodType<Return>;
+}
+
+/** Declare an activity contract. */
+export function activityContract<ArgsSchema extends z.ZodTypeAny, ReturnSchema extends z.ZodTypeAny = never>(
+  name: string,
+  args: ArgsSchema,
+  returns?: ReturnSchema,
+): ActivityContract<z.infer<ArgsSchema>, ReturnSchema extends z.ZodTypeAny ? z.infer<ReturnSchema> : unknown> {
+  return {
+    [CONTRACT_BRAND]: true,
+    name,
+    args,
+    ...(returns ? { returns } : {}),
+  } as ActivityContract<z.infer<ArgsSchema>, ReturnSchema extends z.ZodTypeAny ? z.infer<ReturnSchema> : unknown>;
+}
+
+/** Structural guard for a value produced by {@link activityContract}. */
+export function isActivityContract(value: unknown): value is ActivityContract {
+  return typeof value === "object" && value !== null && (value as Record<symbol, unknown>)[CONTRACT_BRAND] === true;
+}
+
+/**
+ * Add every {@link ActivityContract} exported from an activity-contracts
+ * module to `into`, keyed by its declared `name` — the schema-shaped sibling
+ * of `activity-registry.ts`'s `collectActivities`.
+ */
+export function collectActivityContracts(mod: Record<string, unknown>, into: Map<string, ActivityContract>): void {
+  for (const value of Object.values(mod)) {
+    if (isActivityContract(value)) into.set(value.name, value);
+  }
+}
+
+// ── Validation ──────────────────────────────────────────────────────────────
+
+export interface ActivityContractIssue {
+  /** The Op the offending step belongs to. */
+  opName: string;
+  /** The phase the offending step belongs to. */
+  phase: string;
+  /** The activity name the offending step calls. */
+  fn: string;
+  /** Human-readable description of the mismatch. */
+  message: string;
+}
+
+/** Every `ActivityStep` in a phase, including ones nested inside an `EffectStep`. */
+function activityStepsOf(steps: StepDefinition[]): ActivityStep[] {
+  return steps.flatMap((s) => (s.kind === "activity" ? [s] : s.kind === "effect" ? s.steps.filter((n) => n.kind === "activity") : []));
+}
+
+// Same global symbol `step-output-ref.ts` brands a `StepOutputRef` with —
+// `Symbol.for(...)` interns by string key, so this recognizes one without
+// importing that module (which itself imports `pathExistsInSchema` below;
+// importing the other way would make the two files a cycle).
+const STEP_OUTPUT_REF_BRAND = Symbol.for("chant.op.stepOutputRef");
+function isStepOutputRefValue(value: unknown): boolean {
+  return typeof value === "object" && value !== null && (value as Record<symbol, unknown>)[STEP_OUTPUT_REF_BRAND] === true;
+}
+
+/** The value at `path` (a zod issue's `.path`) inside `obj`, or `undefined` if any segment doesn't resolve. */
+function valueAtPath(obj: unknown, path: ReadonlyArray<PropertyKey>): unknown {
+  let current = obj;
+  for (const segment of path) {
+    if (current === null || typeof current !== "object") return undefined;
+    current = (current as Record<PropertyKey, unknown>)[segment];
+  }
+  return current;
+}
+
+/** Unwrap `ZodOptional`/`ZodNullable`/`ZodDefault` (and similar) down to the schema they wrap. */
+function unwrap(schema: z.ZodTypeAny): z.ZodTypeAny {
+  let current = schema;
+  while (typeof (current as unknown as { unwrap?: () => z.ZodTypeAny }).unwrap === "function") {
+    current = (current as unknown as { unwrap: () => z.ZodTypeAny }).unwrap();
+  }
+  return current;
+}
+
+/**
+ * Does dot-path `path` resolve to a field that exists on `schema`? Object
+ * shapes only — a return schema whose root (or an intermediate segment) is
+ * a `z.record(...)`/`z.array(...)` rather than a `z.object(...)` hard-errors
+ * (returns `false`) instead of skipping, deliberately (chant #1290 comment
+ * on #1288's pre-merge review): a record's keys are dynamic and an array's
+ * elements are index-addressed, neither of which a dot-path segment can
+ * check against in any way that's more meaningful than "the author probably
+ * meant something else." No declared `returns` schema needs this today, so
+ * there's no live case to design against yet. The escape hatch is an empty
+ * path — `outcomeAttribute.from` omitted, or a {@link StepOutputRef}'s
+ * `path` omitted — which references the whole return value and never calls
+ * this function; a record/array-returning activity's whole value is always
+ * a valid reference target.
+ */
+export function pathExistsInSchema(schema: z.ZodTypeAny, path: string): boolean {
+  return schemaAtPath(schema, path.split(".")) !== undefined;
+}
+
+/**
+ * The zod schema at property-key path `path` inside `schema`, walking
+ * through `z.ZodObject` shapes only (unwrapping optional/nullable/default at
+ * each level, same as {@link pathExistsInSchema}). `undefined` when a
+ * segment doesn't resolve, or an intermediate schema isn't a `z.ZodObject` —
+ * same record/array hard-stop {@link pathExistsInSchema} documents. An empty
+ * `path` returns `schema` itself (unwrapped).
+ */
+export function schemaAtPath(schema: z.ZodTypeAny, path: ReadonlyArray<string>): z.ZodTypeAny | undefined {
+  let current = unwrap(schema);
+  for (const segment of path) {
+    if (!(current instanceof z.ZodObject)) return undefined;
+    const shape = current.shape as Record<string, z.ZodTypeAny>;
+    if (!(segment in shape)) return undefined;
+    current = unwrap(shape[segment]);
+  }
+  return current;
+}
+
+/**
+ * A primitive-shape classification of a zod schema — `string`/`number`/
+ * `boolean`/`object`/`array`, or `undefined` for anything else (a union,
+ * enum, literal, `z.any()`/`z.unknown()`, a transform, …). Used by the
+ * step-output-ref cross-contract type check (chant #1950-3) to compare a
+ * producer's declared return type against a consumer's declared arg type at
+ * the same structural position — deliberately shallow: it bails (returns
+ * `undefined`) on anything fancier than these five kinds rather than trying
+ * to reason about it, per that check's "bail out silently" design.
+ */
+export type PrimitiveSchemaKind = "string" | "number" | "boolean" | "object" | "array";
+
+export function primitiveKindOf(schema: z.ZodTypeAny): PrimitiveSchemaKind | undefined {
+  const s = unwrap(schema);
+  if (s instanceof z.ZodString) return "string";
+  if (s instanceof z.ZodNumber) return "number";
+  if (s instanceof z.ZodBoolean) return "boolean";
+  if (s instanceof z.ZodObject) return "object";
+  if (s instanceof z.ZodArray) return "array";
+  return undefined;
+}
+
+/**
+ * Validate every activity step in an Op's phases (main and `onFailure`)
+ * against a contract map. A step whose `fn` has no entry in `contracts` is
+ * skipped — Stage 1 is opt-in per activity, not a hard requirement that
+ * every activity have a declared contract.
+ *
+ * Catches the four failure classes chant #1288 names:
+ *  - an unrecognized `profile` (checked against {@link KNOWN_ACTIVITY_PROFILES}, independent of whether `fn` has a contract),
+ *  - an args key the declared schema doesn't recognize,
+ *  - an args value of the wrong type (including a required key that's missing),
+ *  - an `outcomeAttribute.from` path that can't exist on the declared return type.
+ */
+export function validateActivitySteps(
+  config: Pick<OpConfig, "name" | "phases" | "onFailure">,
+  contracts: ReadonlyMap<string, ActivityContract>,
+): ActivityContractIssue[] {
+  const issues: ActivityContractIssue[] = [];
+  const phasesToWalk: PhaseDefinition[] = [...config.phases, ...(config.onFailure ?? [])];
+
+  for (const phase of phasesToWalk) {
+    for (const step of activityStepsOf(phase.steps)) {
+      if (step.profile && !(KNOWN_ACTIVITY_PROFILES as readonly string[]).includes(step.profile)) {
+        issues.push({
+          opName: config.name,
+          phase: phase.name,
+          fn: step.fn,
+          message: `unknown profile "${step.profile}" (known: ${KNOWN_ACTIVITY_PROFILES.join(", ")})`,
+        });
+      }
+
+      const contract = contracts.get(step.fn);
+      if (!contract) continue;
+
+      const parsed = contract.args.safeParse(step.args ?? {});
+      if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+          // A step-output reference (#1290) sitting at this path is a
+          // placeholder object at build time, not the value it will
+          // resolve to — so an args-schema type mismatch here is a false
+          // positive; TMP013 (`validateStepOutputRefs`) is what validates
+          // a reference, against the *producer's* declared return schema.
+          // An unrecognized-key issue's path is the parent object (`[]`
+          // for a top-level extra key), which is never itself a reference,
+          // so a genuinely misspelled key is still caught either way.
+          if (isStepOutputRefValue(valueAtPath(step.args, issue.path))) continue;
+          const path = issue.path.length > 0 ? issue.path.join(".") : "(args)";
+          issues.push({ opName: config.name, phase: phase.name, fn: step.fn, message: `args.${path}: ${issue.message}` });
+        }
+      }
+
+      if (step.outcomeAttribute?.from && contract.returns && !pathExistsInSchema(contract.returns, step.outcomeAttribute.from)) {
+        issues.push({
+          opName: config.name,
+          phase: phase.name,
+          fn: step.fn,
+          message: `outcomeAttribute.from "${step.outcomeAttribute.from}" does not exist on "${step.fn}"'s declared return type`,
+        });
+      }
+    }
+  }
+
+  return issues;
+}