@intentius/chant 0.46.0 → 0.49.0

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

@@ -104,6 +104,33 @@ describe("EVL001: non-literal-expression", () => {
     expect(diags[0].ruleId).toBe("EVL001");
   });
 
+  // chant #1544 — the single-action Composite() wrapper idiom
+  // (`Checkout({...}).step`) every lexicon's own docs/examples embed inline
+  // inside a `Job`'s `steps:` array must not trip EVL001.
+  test("allows a composite call's .step access embedded in an array", () => {
+    const ctx = createContext(`new Job({ "runs-on": "ubuntu-latest", steps: [Checkout({}).step] });`);
+    const diags = evl001NonLiteralExpressionRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("allows a composite call's .step access as a direct property value", () => {
+    const ctx = createContext(`new Job({ step: Checkout({ ref: "main" }).step });`);
+    const diags = evl001NonLiteralExpressionRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("still flags a call accessing a non-.step property", () => {
+    const ctx = createContext(`new Job({ steps: [Checkout({}).output] });`);
+    const diags = evl001NonLiteralExpressionRule.check(ctx);
+    expect(diags).toHaveLength(1);
+  });
+
+  test("still flags a bare call (no trailing .step access)", () => {
+    const ctx = createContext(`new Bucket({ name: getName() });`);
+    const diags = evl001NonLiteralExpressionRule.check(ctx);
+    expect(diags).toHaveLength(1);
+  });
+
   test("flags multiple violations", () => {
     const ctx = createContext(`new Bucket({ a: foo(), b: bar() });`);
     const diags = evl001NonLiteralExpressionRule.check(ctx);

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

@@ -31,7 +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) {
-          const violation = checkObjectMember(prop, context.intrinsics);
+          // 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);
           if (violation) {
             const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
               violation.node.getStart(context.sourceFile),

package/src/lint/rules/index.ts

@@ -26,6 +26,8 @@ export { evl010CompositeNoTransformRule } from "./evl010-composite-no-transform"
 export { cor017CompositeNameMatchRule } from "./cor017-composite-name-match";
 export { cor018CompositePreferLexiconTypeRule } from "./cor018-composite-prefer-lexicon-type";
 export { cor021EnvLiteralNameRule } from "./cor021-env-literal-name";
+export { cor022ReceiptLeafRule, collectReceiptVariables, receiptFactoryCall } from "./cor022-receipt-leaf";
+export { cor024ReceiptSecretPointerRule } from "./cor024-receipt-secret-pointer";
 export { isInsideCompositeFactory } from "./composite-scope";
 
 import { flatDeclarationsRule } from "./flat-declarations";
@@ -50,9 +52,11 @@ import { evl010CompositeNoTransformRule } from "./evl010-composite-no-transform"
 import { cor017CompositeNameMatchRule } from "./cor017-composite-name-match";
 import { cor018CompositePreferLexiconTypeRule } from "./cor018-composite-prefer-lexicon-type";
 import { cor021EnvLiteralNameRule } from "./cor021-env-literal-name";
+import { cor022ReceiptLeafRule } from "./cor022-receipt-leaf";
+import { cor024ReceiptSecretPointerRule } from "./cor024-receipt-secret-pointer";
 
 /**
- * Load all 22 core lint rules (COR + EVL).
+ * Load all 24 core lint rules (COR + EVL).
  */
 export function loadCoreRules(): LintRule[] {
   return [
@@ -78,5 +82,7 @@ export function loadCoreRules(): LintRule[] {
     cor017CompositeNameMatchRule,
     cor018CompositePreferLexiconTypeRule,
     cor021EnvLiteralNameRule,
+    cor022ReceiptLeafRule,
+    cor024ReceiptSecretPointerRule,
   ];
 }

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/builders.ts

@@ -1,5 +1,7 @@
 import { OpResource } from "./resource";
-import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./types";
+import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep } from "./types";
+import { isEffectReceipt, type EffectReceiptDeclaration } from "../effect-receipt";
+import { receiptCheckInput } from "./receipt-store";
 
 // ── Core builders ─────────────────────────────────────────────────────────────
 
@@ -58,6 +60,62 @@ export function gate(
   };
 }
 
+/**
+ * Wrap nested steps in read-compare-run-write over an effect receipt (#1834,
+ * epic #1703). At run: read the live receipt through the receipt store,
+ * compare it against the resolved expectation, and on a match skip the nested
+ * steps ("effect already applied"). On a mismatch the nested steps run in
+ * authored order, and ONLY when every one of them succeeds is the receipt
+ * written — last, once. This step is the sole writer of a receipt (decision
+ * 3); a nested-step failure leaves the receipt untouched (stale), so the next
+ * run re-proposes the effect.
+ *
+ * `receipt` is the typed EffectReceipt declaration — import the const from
+ * your receipts module. There is no string form: a receipt named by string
+ * would sever the step from the declaration that lint, plan, and the lexicon
+ * row all key on.
+ *
+ * A gate authored inside `steps` pauses only when the effect will fire (the
+ * matched path never reaches it). The receipt-store activities (`receiptRead`,
+ * `receiptWrite`) are provided by the receipt row's lexicon (#1835, aws).
+ *
+ * @example
+ * ```ts
+ * import { seededReceipt } from "./receipts";
+ * phase("Seed", [
+ *   effect(seededReceipt, [
+ *     shell("npm run db:seed"),
+ *   ]),
+ * ]),
+ * ```
+ */
+export function effect(
+  receipt: EffectReceiptDeclaration,
+  steps: Array<ActivityStep | GateStep>,
+  opts?: { description?: string },
+): EffectStep {
+  if (!isEffectReceipt(receipt)) {
+    throw new Error(
+      "effect(): `receipt` must be the EffectReceipt declaration itself — import the const; there is no string form",
+    );
+  }
+  for (const step of steps) {
+    if ((step as { kind?: unknown }).kind === "effect") {
+      throw new Error(
+        `effect("${receipt.name}"): effect steps do not nest — one receipt witnesses one effect`,
+      );
+    }
+  }
+  const { receipt: ref, expectation } = receiptCheckInput(receipt);
+  return {
+    kind: "effect",
+    receipt: ref,
+    ...(expectation !== undefined ? { expectation } : {}),
+    steps,
+    ...(opts?.description ? { description: opts.description } : {}),
+  };
+}
+
 // ── Pre-built activity shortcuts ──────────────────────────────────────────────
 
 /**
@@ -100,6 +158,22 @@ export const helmInstall = (
   return activity("helmInstall", { name, chart, ...args }, profile ?? "longInfra");
 };
 
+/**
+ * Deploy a recorded pinned render by its `sha256:` content digest (chant
+ * #1242): the helm lexicon's `helmInstall` activity loads the render from
+ * the render store, verifies the digest, and installs those exact bytes as
+ * a structure-preserving wrapper chart — no deploy-time render. Defaults to
+ * the `longInfra` profile (override via `opts.profile`).
+ */
+export const helmInstallPinned = (
+  name: string,
+  contentDigest: string,
+  opts?: { namespace?: string; profile?: ActivityStep["profile"]; [k: string]: unknown },
+): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("helmInstall", { name, contentDigest, ...args }, profile ?? "longInfra");
+};
+
 /** Poll for stack readiness (kubectl rollout, CloudFormation complete, etc). Defaults to the `k8sWait` profile (override via `opts.profile`). */
 export const waitForStack = (name: string, opts?: Record<string, unknown>): ActivityStep => {
   const { args, profile } = takeProfile(opts);
@@ -133,6 +207,28 @@ export const shell = (
 ): ActivityStep =>
   activity("shellCmd", { cmd, ...(opts?.env ? { env: opts.env } : {}) }, opts?.profile);
 
+/**
+ * Ensure a `generated-once` secret exists in the target store (#1829, epic
+ * #1365). The op-step surface over the same engine as the `ensure-secret`
+ * capability verb (`ensureSecretMaterialization`, core's
+ * secret-materialization module): read-then-write — if the secret exists, its
+ * declared key-set and any declared `metadata` are verified and the step
+ * stops (present means done); if absent, one value per key is minted at
+ * apply time and written straight to the store. Never mints over an existing
+ * value, never rotates implicitly; a mismatch fails the step loudly, naming
+ * key names and metadata keys — never values. No output of the activity
+ * carries secret material. The backing activity is provided by the store's
+ * lexicon (k8s, #1830).
+ */
+export const ensureSecret = (
+  name: string,
+  keys: string[],
+  opts?: { metadata?: Record<string, string>; profile?: ActivityStep["profile"]; [k: string]: unknown },
+): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("ensureSecret", { name, keys, ...args }, profile);
+};
+
 /** Run `chant teardown` in the given project directory. Uses `longInfra` profile. */
 export const teardown = (path: string): ActivityStep =>
   activity("chantTeardown", { path }, "longInfra");
@@ -200,6 +296,48 @@ export const k3dDown = (name: string, opts?: Record<string, unknown>): ActivityS
   return activity("k3dDown", { name, ...args }, profile ?? "fastIdempotent");
 };
 
+/**
+ * Run the pinned k3s installer against a reachable host (`role`: `"server"`
+ * or `"agent"`). Idempotent on an already-installed matching version.
+ * Defaults to the `longInfra` profile (the installer downloads and starts
+ * the binary); override via `opts.profile`.
+ *
+ * The implementation lives in the k3s lexicon (chant #1601) — the project's
+ * `chant.config.ts` must list `"k3s"` in `lexicons` for the activity to load.
+ * Bounded exactly as `k3dUp`/`k3dDown` (chant #1410): drives the reachable-host
+ * case only, no host provisioning, no SSH orchestration.
+ *
+ * `opts` accepts `configFile` (required — path to the chant-emitted
+ * config.yaml, passed as `--config`), `version` (overrides the lexicon's
+ * pinned `INSTALL_K3S_VERSION`), and `tokenFile` (path to a file holding the
+ * join token, passed to the installer as `K3S_TOKEN_FILE`). There is no
+ * `token` option — the join secret's value never travels through this step;
+ * only a file path does (the #1601 token boundary, same stance as #1365).
+ */
+export const k3sInstall = (
+  role: "server" | "agent",
+  opts: { configFile: string; version?: string; tokenFile?: string; profile?: ActivityStep["profile"]; [k: string]: unknown },
+): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("k3sInstall", { role, ...args }, profile ?? "longInfra");
+};
+
+/**
+ * Uninstall k3s from a reachable host (`role`: `"server"` or `"agent"`).
+ * Defaults to the `fastIdempotent` profile (override via `opts.profile`).
+ * Implementation lives in the k3s lexicon (chant #1601) — requires `"k3s"`
+ * in the project's `lexicons`. A host where k3s was never installed is a
+ * no-op success, the same shape as `k3dDown` against an already-gone
+ * cluster.
+ */
+export const k3sUninstall = (
+  role: "server" | "agent",
+  opts?: Record<string, unknown>,
+): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("k3sUninstall", { role, ...args }, profile ?? "fastIdempotent");
+};
+
 /**
  * Boot a local Floci AWS emulator in Docker and point subsequent steps at it —
  * sets `AWS_ENDPOINT_URL` + test creds in the process env so a following