@intentius/chant 0.46.0 → 0.50.0

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

package/src/op/builders-exports.test.ts

@@ -50,7 +50,23 @@ describe("op builders are all reachable (#1715)", () => {
       "spriteApplyServices", "spriteTaskCreate", "spriteTaskRefresh",
       "spriteTaskRelease", "spritesUp", "spritesDown",
     ]);
-    const expected = Object.keys(builders).filter((n) => !FLY_SURFACE.has(n));
+    // chant #1288 Stage 2 — these are the temporal lexicon's OWN activities
+    // (build.ts, shell.ts, wait.ts, ...), so its barrel re-exports a fully
+    // typed twin from its own `./op/builders` instead of core's untyped
+    // original — same name, same import path, deliberately not sourced from
+    // `@intentius/chant/op` any more. See `lexicons/temporal/src/index.ts`
+    // and `lexicons/temporal/src/op/builders.ts`.
+    const TEMPORAL_TYPED_SURFACE = new Set([
+      "build", "shell", "waitForStack", "lifecycleSnapshot", "teardown", "envTeardown", "httpCheck", "policyGate",
+    ]);
+    // chant #1288 Stage 2 — an internal helper (`takeProfile`'s sibling) for
+    // the lexicon-owned typed step-builder wrappers to reuse, not an
+    // Op-authoring primitive itself; nothing authors an Op with it directly,
+    // so it has no place in the Op-authoring barrel.
+    const INTERNAL_HELPERS = new Set(["takeProfileAndId"]);
+    const expected = Object.keys(builders).filter(
+      (n) => !FLY_SURFACE.has(n) && !TEMPORAL_TYPED_SURFACE.has(n) && !INTERNAL_HELPERS.has(n),
+    );
     const missing = expected.filter((name) => !reExported.has(name));
     expect(
       missing,

package/src/op/builders.ts

@@ -1,5 +1,19 @@
 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";
+import { makeOutProxy, type StepOutputRef } from "./step-output-ref";
+
+/** An `activity()` result — the plain `ActivityStep` shape plus the `.out` reference sugar (#1290). */
+export interface NamedActivityStep extends ActivityStep {
+  /**
+   * `step.out.someField` builds a {@link StepOutputRef} into this step's
+   * declared return value, for use in a later step's `args`. Throws on
+   * access if this step has no `id` (pass one via `activity()`'s third
+   * argument) — there is nothing for a reference to name otherwise.
+   */
+  readonly out: Record<string, StepOutputRef>;
+}
 
 // ── Core builders ─────────────────────────────────────────────────────────────
 
@@ -31,18 +45,44 @@ export function phase(
   return { name, steps, ...(opts?.parallel ? { parallel: true } : {}) };
 }
 
-/** Reference a pre-built or custom activity by function name. */
+/**
+ * Reference a pre-built or custom activity by function name.
+ *
+ * The third argument is a profile string (unchanged) or, to name the step
+ * so a later step can reference its output (#1290), an options object:
+ * `activity("lifecycleDiff", { env: "prod" }, { id: "diff" })`. Named or
+ * not, the result carries `.out` — `diff.out.driftedStacks` builds a
+ * reference to this step's declared return value; see `stepOutput()` in
+ * `@intentius/chant/op` for the equivalent on a step authored as a plain
+ * object literal instead of via this builder.
+ */
 export function activity(
   fn: string,
   args?: Record<string, unknown>,
-  profile?: ActivityStep["profile"],
-): ActivityStep {
-  return {
+  opts?: ActivityStep["profile"] | { profile?: ActivityStep["profile"]; id?: string },
+): NamedActivityStep {
+  const profile = typeof opts === "string" ? opts : opts?.profile;
+  const id = typeof opts === "string" ? undefined : opts?.id;
+  const step = {
     kind: "activity",
     fn,
     ...(args && Object.keys(args).length > 0 ? { args } : {}),
     ...(profile ? { profile } : {}),
-  };
+    ...(id ? { id } : {}),
+  } as NamedActivityStep;
+  Object.defineProperty(step, "out", {
+    enumerable: false,
+    get(): Record<string, StepOutputRef> {
+      if (!step.id) {
+        throw new Error(
+          `activity(${JSON.stringify(fn)}, ...).out: this step has no id — pass one via ` +
+            `activity(fn, args, { id: "..." }) before referencing its output.`,
+        );
+      }
+      return makeOutProxy(step.id);
+    },
+  });
+  return step;
 }
 
 /** Insert a human gate — the workflow pauses until the named signal is received. */
@@ -58,6 +98,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 ──────────────────────────────────────────────
 
 /**
@@ -78,6 +174,22 @@ function takeProfile(
   return { args, profile };
 }
 
+/**
+ * {@link takeProfile}'s sibling for the typed, lexicon-owned step-builder
+ * wrappers added in chant #1288 Stage 2 (e.g. `kubectlApply` in
+ * `@intentius/chant-lexicon-k8s`): also pulls `id` out of the opts bag so it
+ * routes to the step's `id` field (enabling `.out` — #1290) instead of
+ * leaking into the activity's args, the same way `profile` would without
+ * this split.
+ */
+export function takeProfileAndId(
+  opts: (Record<string, unknown> & { profile?: ActivityStep["profile"]; id?: string }) | undefined,
+): { args: Record<string, unknown>; profile?: ActivityStep["profile"]; id?: string } {
+  if (!opts) return { args: {} };
+  const { profile, id, ...args } = opts as { profile?: ActivityStep["profile"]; id?: string } & Record<string, unknown>;
+  return { args, profile, id };
+}
+
 /** Run an npm build script in the given project directory. `opts.script` selects the script (default `build`, e.g. `build:aws`); `opts.env` adds env vars. */
 export const build = (path: string, opts?: Record<string, unknown>): ActivityStep => {
   const { args, profile } = takeProfile(opts);
@@ -100,6 +212,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 +261,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 +350,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