@intentius/chant 0.46.0 → 0.50.0

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/okf-read.test.ts

@@ -0,0 +1,149 @@
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { loadOkfBundle, bindConcepts } from "./okf-read";
+import { buildOkfBundle } from "./okf";
+import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+
+function decl<T extends object>(base: T): Declarable & T {
+  return { [DECLARABLE_MARKER]: true, ...base } as Declarable & T;
+}
+
+const TEST_DIR = join(import.meta.dirname, "__test_okf_read__");
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+function write(relPath: string, content: string): void {
+  const full = join(TEST_DIR, relPath);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, content);
+}
+
+describe("loadOkfBundle", () => {
+  test("a missing directory yields an empty bundle, not an error", async () => {
+    const bundle = await loadOkfBundle(join(TEST_DIR, "does-not-exist"));
+    expect(bundle.concepts).toEqual([]);
+  });
+
+  test("skips index.md and log.md, at any depth", async () => {
+    write("index.md", "---\nokf_version: '0.2'\n---\n");
+    write("log.md", "---\ntype: log\n---\nsome log\n");
+    write("nested/log.md", "---\ntype: log\n---\nnested log\n");
+    write("decisions/keep.md", "---\ntype: decision\ntitle: Keep me\n---\nbody\n");
+
+    const bundle = await loadOkfBundle(TEST_DIR);
+    expect(bundle.concepts.map((c) => c.path)).toEqual(["decisions/keep.md"]);
+  });
+
+  test("passes through unknown type values and extra frontmatter keys", async () => {
+    write("weird.md", "---\ntype: some-unknown-type\ncustom_field: hello\n---\nbody text\n");
+
+    const bundle = await loadOkfBundle(TEST_DIR);
+    expect(bundle.concepts).toHaveLength(1);
+    const [concept] = bundle.concepts;
+    expect(concept.type).toBe("some-unknown-type");
+    expect(concept.frontmatter.custom_field).toBe("hello");
+    expect(concept.body).toContain("body text");
+  });
+
+  test("skips a file with unparseable frontmatter, warns, and does not affect other files", async () => {
+    write("broken.md", "not frontmatter at all\n");
+    write("fine.md", "---\ntype: decision\ntitle: Fine\n---\nbody\n");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const bundle = await loadOkfBundle(TEST_DIR);
+
+    expect(bundle.concepts.map((c) => c.path)).toEqual(["fine.md"]);
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  test("never rejects the bundle for a malformed file — an empty frontmatter block loads with an empty type", async () => {
+    write("empty-front.md", "---\n---\nbody\n");
+    const bundle = await loadOkfBundle(TEST_DIR);
+    expect(bundle.concepts).toHaveLength(1);
+    expect(bundle.concepts[0].type).toBe("");
+    expect(bundle.concepts[0].binds).toEqual([]);
+  });
+
+  test("binds accepts a single name", async () => {
+    write("single.md", "---\ntype: decision\nbinds: myBucket\n---\nbody\n");
+    const bundle = await loadOkfBundle(TEST_DIR);
+    expect(bundle.concepts[0].binds).toEqual(["myBucket"]);
+  });
+
+  test("binds accepts a list", async () => {
+    write("multi.md", "---\ntype: decision\nbinds:\n  - myBucket\n  - vpc\n---\nbody\n");
+    const bundle = await loadOkfBundle(TEST_DIR);
+    expect(bundle.concepts[0].binds).toEqual(["myBucket", "vpc"]);
+  });
+
+  test("a concept without binds loads as unbound and is legitimate", async () => {
+    write("orphan.md", "---\ntype: runbook\ntitle: Incident response\n---\nbody\n");
+    const bundle = await loadOkfBundle(TEST_DIR);
+    expect(bundle.concepts[0].binds).toEqual([]);
+  });
+});
+
+describe("bindConcepts", () => {
+  test("returns bound concepts per entity name plus unresolved bindings", async () => {
+    write("bound.md", "---\ntype: decision\ntitle: Bound\nbinds: myBucket\n---\nbody\n");
+    write("multi.md", "---\ntype: decision\ntitle: Spans two\nbinds:\n  - myBucket\n  - vpc\n---\nbody\n");
+    write("stale.md", "---\ntype: decision\ntitle: Stale\nbinds: ghost\n---\nbody\n");
+    write("orphan.md", "---\ntype: runbook\ntitle: Orphan\n---\nbody\n");
+
+    const bundle = await loadOkfBundle(TEST_DIR);
+    const entities = new Map<string, Declarable>([
+      ["myBucket", decl({ lexicon: "aws", entityType: "AWS::S3::Bucket" })],
+      ["vpc", decl({ lexicon: "gcp", entityType: "Vpc" })],
+    ]);
+
+    const { bound, unresolved } = bindConcepts(bundle, entities);
+
+    expect(bound.get("myBucket")?.map((c) => c.title)).toEqual(["Bound", "Spans two"]);
+    expect(bound.get("vpc")?.map((c) => c.title)).toEqual(["Spans two"]);
+    expect(bound.has("ghost")).toBe(false);
+    expect(unresolved).toHaveLength(1);
+    expect(unresolved[0].name).toBe("ghost");
+    expect(unresolved[0].concept.title).toBe("Stale");
+  });
+
+  test("an entity with no bound concepts is absent from the map, never present with []", async () => {
+    const bundle = await loadOkfBundle(join(TEST_DIR, "empty"));
+    const entities = new Map<string, Declarable>([["vpc", decl({ lexicon: "gcp", entityType: "Vpc" })]]);
+    const { bound, unresolved } = bindConcepts(bundle, entities);
+    expect(bound.size).toBe(0);
+    expect(unresolved).toEqual([]);
+  });
+});
+
+describe("round trip with buildOkfBundle (#1058) — the emitter never writes binds", () => {
+  test("reading back an emitted bundle yields zero bindings", async () => {
+    const bucket = decl({ lexicon: "aws", entityType: "AWS::S3::Bucket" });
+    const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+    const entities = new Map<string, Declarable>([
+      ["myBucket", bucket],
+      ["vpc", vpc],
+    ]);
+    const dependencies = new Map([["myBucket", new Set(["vpc"])]]);
+
+    for (const file of buildOkfBundle({ entities, dependencies })) {
+      write(file.path, file.content);
+    }
+
+    const bundle = await loadOkfBundle(TEST_DIR);
+    // index.md is reserved and skipped; the two entity concepts load.
+    expect(bundle.concepts.map((c) => c.path).sort()).toEqual(["aws/myBucket.md", "gcp/vpc.md"]);
+    expect(bundle.concepts.every((c) => c.binds.length === 0)).toBe(true);
+
+    const { bound, unresolved } = bindConcepts(bundle, entities);
+    expect(bound.size).toBe(0);
+    expect(unresolved).toEqual([]);
+  });
+});

package/src/okf-read.ts

@@ -0,0 +1,197 @@
+import { readdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import type { Declarable } from "./declarable";
+import { splitFrontmatter } from "./okf";
+import { parseYAML } from "./yaml";
+
+/**
+ * OKF bundle reader (#1864, design #1059, epic #1057) — the input half of
+ * `./okf.ts`'s emitter: loads a project-authored knowledge bundle from disk
+ * and binds its concepts to discovered entities.
+ *
+ * Tolerant to the letter of the OKF v0.2 spec (§11), the same posture
+ * `okfConformanceProblems` enforces on the emit side: unknown `type` values
+ * and extra frontmatter keys pass through untouched, a file with unparseable
+ * or missing frontmatter is skipped with a warning, and nothing here ever
+ * rejects the bundle — a missing knowledge directory included.
+ */
+
+const RESERVED_OKF_FILES = new Set(["index.md", "log.md"]);
+
+/**
+ * One authored concept document, parsed from a bundle. Deliberately thinner
+ * than the emit side's internal `Concept` (`./okf.ts`) — this is what a
+ * *reader* trusts, and per the #1059 design that is `type`/`title` plus the
+ * single frontmatter key chant interprets, `binds`. Everything else an
+ * author wrote rides along in {@link frontmatter} unexamined, so a consumer
+ * that needs a project-specific key (a future `category`, say) can still
+ * reach it without a reader change.
+ */
+export interface OkfConcept {
+  /** Bundle-relative path (forward-slash separated), e.g. "decisions/public-assets.md". */
+  path: string;
+  /** The frontmatter `type`. May be empty — the reader never rejects a concept for it, unlike the emitter's conformance check. */
+  type: string;
+  /** Frontmatter `title`, when the author set one. */
+  title?: string;
+  /**
+   * This concept's `binds` frontmatter key, normalized to a list — one name,
+   * several, or `[]` for "declared no binding, and that's legitimate."
+   * Structural-looking keys (`name`, `lexicon`, `kind`) are deliberately
+   * *not* surfaced here or anywhere else on this type: the reader interprets
+   * exactly `binds` (#1059's precedence-by-construction), so authored and
+   * inferred knowledge cannot conflict at the fact level.
+   */
+  binds: string[];
+  /** Every frontmatter key this concept's document carries, `binds` included, verbatim. */
+  frontmatter: Record<string, unknown>;
+  /** Markdown body (everything after the closing `---`), unchanged. */
+  body: string;
+}
+
+/** A loaded OKF knowledge bundle: every authored concept found, reserved files already excluded. */
+export interface OkfBundle {
+  concepts: OkfConcept[];
+}
+
+/** `binds` accepts one name or a list (#1059); anything else is treated as "no binding" rather than rejecting the concept. */
+function normalizeBinds(value: unknown): string[] {
+  if (typeof value === "string") return value.length > 0 ? [value] : [];
+  if (Array.isArray(value)) return value.filter((v): v is string => typeof v === "string" && v.length > 0);
+  return [];
+}
+
+/** Recursively collect every `.md` file under `dir`, as bundle-relative (forward-slash) paths paired with their absolute path. */
+async function findMarkdownFiles(dir: string): Promise<Array<{ relPath: string; fullPath: string }>> {
+  const found: Array<{ relPath: string; fullPath: string }> = [];
+
+  async function scan(current: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      return; // unreadable directory: silently skip, same posture as findInfraFiles
+    }
+    for (const entry of entries) {
+      const fullPath = join(current, entry.name);
+      if (entry.isDirectory()) {
+        await scan(fullPath);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        const relPath = relative(dir, fullPath).split(sep).join("/");
+        found.push({ relPath, fullPath });
+      }
+    }
+  }
+
+  await scan(dir);
+  return found;
+}
+
+/**
+ * Load every authored concept from an OKF knowledge bundle directory.
+ * `index.md`/`log.md` are skipped (reserved, by basename, at any depth —
+ * matching `okfConformanceProblems`'s check on the emit side). A directory
+ * that does not exist yields an empty bundle, not an error: the #1059 design
+ * treats a missing `knowledge/` as "this project has none yet," the same
+ * posture as a project with no lexicons configured.
+ *
+ * A file that fails to parse — no frontmatter block, unparseable YAML, or
+ * frontmatter that isn't a mapping — is skipped with a `console.warn` and
+ * does not affect any other file. Nothing here throws.
+ */
+export async function loadOkfBundle(dir: string): Promise<OkfBundle> {
+  if (!existsSync(dir)) return { concepts: [] };
+
+  const concepts: OkfConcept[] = [];
+  for (const { relPath, fullPath } of await findMarkdownFiles(dir)) {
+    if (RESERVED_OKF_FILES.has(relPath.split("/").pop()!)) continue;
+
+    let content: string;
+    try {
+      content = await readFile(fullPath, "utf8");
+    } catch {
+      console.warn(`[chant] warning: knowledge bundle concept "${relPath}" could not be read, skipping`);
+      continue;
+    }
+
+    const split = splitFrontmatter(content);
+    if (!split) {
+      console.warn(`[chant] warning: knowledge bundle concept "${relPath}" has no frontmatter block, skipping`);
+      continue;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = parseYAML(split.frontmatter);
+    } catch {
+      console.warn(`[chant] warning: knowledge bundle concept "${relPath}" has unparseable frontmatter, skipping`);
+      continue;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      console.warn(`[chant] warning: knowledge bundle concept "${relPath}" frontmatter is not a mapping, skipping`);
+      continue;
+    }
+
+    const frontmatter = parsed as Record<string, unknown>;
+    concepts.push({
+      path: relPath,
+      type: typeof frontmatter.type === "string" ? frontmatter.type : "",
+      title: typeof frontmatter.title === "string" ? frontmatter.title : undefined,
+      binds: normalizeBinds(frontmatter.binds),
+      frontmatter,
+      body: split.body,
+    });
+  }
+
+  concepts.sort((a, b) => a.path.localeCompare(b.path));
+  return { concepts };
+}
+
+/** {@link bindConcepts}'s result: bound concepts per entity, plus every binding that resolved nothing. */
+export interface BindConceptsResult {
+  /**
+   * Bound concepts keyed by entity logical name — the same names that key
+   * `DiscoveryResult.entities` (`./discovery/index.ts`). An entity with no
+   * bound concepts is absent from the map, never present with `[]`.
+   */
+  bound: Map<string, OkfConcept[]>;
+  /** Every `binds` entry that named no entity in `entities` — chant's own broken-link posture (#1059): a warning for the caller to surface (COR022, #1865), never a load failure. */
+  unresolved: UnresolvedBinding[];
+}
+
+/** One `binds` entry that resolved to nothing. */
+export interface UnresolvedBinding {
+  /** The concept whose `binds` named this entity. */
+  concept: OkfConcept;
+  /** The unresolved logical name. */
+  name: string;
+}
+
+/**
+ * Resolve every concept's `binds` against a project's discovered entities.
+ * `entities` is the same shape `./okf.ts`'s emitter takes, `DiscoveryResult`'s
+ * own `entities` map — a bare logical name is unambiguous within one
+ * discovery pass (#1059's "Rejected options" on binding ambiguity).
+ *
+ * A concept with no `binds` contributes to neither `bound` nor `unresolved`;
+ * an unbound concept is legitimate, not an omission (a runbook, a decision
+ * about the project as a whole).
+ */
+export function bindConcepts(bundle: OkfBundle, entities: Map<string, Declarable>): BindConceptsResult {
+  const bound = new Map<string, OkfConcept[]>();
+  const unresolved: UnresolvedBinding[] = [];
+
+  for (const concept of bundle.concepts) {
+    for (const name of concept.binds) {
+      if (entities.has(name)) {
+        if (!bound.has(name)) bound.set(name, []);
+        bound.get(name)!.push(concept);
+      } else {
+        unresolved.push({ concept, name });
+      }
+    }
+  }
+
+  return { bound, unresolved };
+}

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);
+  });
+});