@intentius/chant 0.124.12 → 0.124.14

package/dist/op/activity-contract-registry.js

@@ -0,0 +1,106 @@
+/**
+ * Activity contract registry — the schema-shaped sibling of
+ * `./activity-registry.ts` (chant #2101).
+ *
+ * `activity-contract.ts` left contract ownership per-caller on purpose: an
+ * activity declares its contract alongside its implementation, and whoever
+ * builds a contract map decides which activities it covers. What was missing
+ * was the other half of that arrangement, a way for the checks that validate
+ * Op steps to SEE a contract a lexicon declared. OPS012 and OPS013
+ * (`../lint/rules/op/`) walk every Op entity in the build, including steps
+ * calling `terraformPlan`, `k3sInstall`, `flyApply` or `gcpApply`, over
+ * core's own static table alone. Since #2122 moved those checks into core
+ * they fire on every project that declares an Op, so an Op built out of one
+ * lexicon's steps failed `chant build` outright even though `loadActivities`
+ * resolves the very same names at run time. Both terraform examples that
+ * carry an Op kept it outside `src/` because of the older, lexicon-hosted
+ * form of the same gap, which meant no example ever proved its Op builds.
+ *
+ * The resolution mirrors activities exactly, by convention:
+ * `@intentius/chant-lexicon-<name>/op/activity-contracts` is imported for
+ * every configured lexicon and every {@link ActivityContract} it exports is
+ * collected, keyed by the contract's declared `name`. A lexicon that ships
+ * no such module is skipped, the same way `loadActivities` skips one that
+ * contributes no activities. A plugin may also hand its contracts over
+ * directly through {@link LexiconActivityContractContributor}, for a lexicon
+ * whose contracts are not reachable at a subpath (a bundled single-file
+ * plugin, a project-local one).
+ *
+ * The merged map reaches a post-synth check as
+ * `PostSynthContext.activityContracts` (`../lint/post-synth.ts`), filled in
+ * by whoever runs the checks: `chant build`, `chant lint` and
+ * `check-lexicon`'s example harness all do. A check merges it over its own
+ * base table rather than replacing it, so a context that carries none (a
+ * hand-built one in a test) behaves exactly as before this existed.
+ */
+import * as coreContracts from "./activities/activity-contracts.js";
+import { collectActivityContracts } from "./activity-contract.js";
+import { importLexiconModule, importLexiconPackage } from "../lexicon-module.js";
+/**
+ * Build the activity-contract map for build-time validation: core's own
+ * contracts (`./activities/activity-contracts`, a static import so a project
+ * that has installed nothing but chant still gets them) plus every contract
+ * the named lexicons contribute.
+ *
+ * `lexicons` may be plain names or plugin-shaped objects; a plugin's
+ * `activityContracts()` is read after its conventional module, so a plugin
+ * that declares both wins on a name collision with itself. Across lexicons,
+ * last one in wins, which is the same rule `loadActivities` applies to
+ * implementations.
+ *
+ * Never throws: an absent lexicon, a missing subpath, or a plugin member that
+ * throws all leave the map as it was.
+ */
+export async function loadActivityContracts(lexicons = []) {
+    const contracts = new Map();
+    collectActivityContracts(coreContracts, contracts);
+    for (const entry of lexicons) {
+        const name = typeof entry === "string" ? entry : entry.name;
+        let contributor = typeof entry === "string" ? undefined : entry;
+        try {
+            // chant #2520 — a lexicon declared by module path has no subpath to
+            // import. Its plugin's `activityContracts()` member stands in for it;
+            // given only the name, the plugin is read from the declared module.
+            const local = await importLexiconModule(name);
+            if (local !== undefined) {
+                contributor ?? (contributor = Object.values(local).find((v) => typeof v === "object" && v !== null && v.name === name &&
+                    typeof v.activityContracts === "function"));
+            }
+            else {
+                const spec = `@intentius/chant-lexicon-${name}/op/activity-contracts`;
+                collectActivityContracts((await importLexiconPackage(spec)), contracts);
+            }
+        }
+        catch {
+            // Lexicon absent or declares no contracts at the conventional subpath.
+        }
+        if (contributor !== undefined && typeof contributor.activityContracts === "function") {
+            try {
+                for (const contract of contributor.activityContracts())
+                    contracts.set(contract.name, contract);
+            }
+            catch {
+                // A plugin member that throws contributes nothing, the same as one that is absent.
+            }
+        }
+    }
+    return contracts;
+}
+/**
+ * Merge a check's own base contracts with the ones the build loaded, into the
+ * map `validateActivitySteps`/`validateStepOutputRefs` take. The loaded set
+ * wins on a name collision: it is the one resolved against the lexicons this
+ * build actually configured, whereas the base table is whatever the check
+ * imported statically.
+ *
+ * `loaded` being `undefined` is the ordinary case for a hand-built
+ * `PostSynthContext` and yields the base table unchanged.
+ */
+export function mergeActivityContracts(base, loaded) {
+    if (!loaded || loaded.size === 0)
+        return base;
+    const merged = new Map(base);
+    for (const [name, contract] of loaded)
+        merged.set(name, contract);
+    return merged;
+}

package/dist/op/activity-contract.js

@@ -0,0 +1,232 @@
+/**
+ * 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` resolves each step's `fn` against a
+ * contract map built from `Object.values()` of an activity-contracts module
+ * and validates `args` and `outcomeAttribute.from` — core's own OPS012
+ * (`../lint/rules/op/ops012-activity-contract.ts`, chant #2122) does this
+ * for every declared Op regardless of which lexicons are configured; a
+ * lexicon's own post-synth check can additionally validate against its own
+ * roster the same way (a lexicon-owned check did this before #2122 moved the
+ * op-model checks to core). A step whose `fn` has no registered
+ * contract is skipped (not an error): this is deliberately incremental — a
+ * contract map opts an activity in by declaring one for it, and the
+ * k8s/aws/azure/gcp/fly activity sets are expected to pick this up one at a
+ * time rather than all at once (see the issue's "worth checking this lands
+ * cleanly" note).
+ *
+ * Ownership of a contract map is per-caller, not a shared cross-lexicon
+ * registry: whoever builds the map (core's OPS012/OPS013, or a lexicon's own
+ * check) decides which activities it covers. A `Chant::Op` step can call an
+ * activity contributed by any lexicon, and `PostSynthContext.entities`
+ * already carries the whole resolved graph to every check, so no new
+ * plumbing is needed for that to work.
+ */
+import { z } from "zod";
+import { outcomeAttributesOf } from "./types.js";
+import { ACTIVITY_PROFILE_NAMES, stepTimeoutProblem } from "./activity-profiles.js";
+/**
+ * Every literal value {@link ActivityStep.profile} may hold, read off
+ * {@link ACTIVITY_PROFILES} itself so the runtime list cannot drift from the
+ * table the type is derived from.
+ */
+export const KNOWN_ACTIVITY_PROFILES = ACTIVITY_PROFILE_NAMES;
+const CONTRACT_BRAND = Symbol.for("chant.op.activityContract");
+/** Declare an activity contract. */
+export function activityContract(name, args, returns, opts) {
+    return {
+        [CONTRACT_BRAND]: true,
+        name,
+        args,
+        ...(returns ? { returns } : {}),
+        ...(opts?.entities && opts.entities.length > 0 ? { entities: opts.entities } : {}),
+    };
+}
+/** Structural guard for a value produced by {@link activityContract}. */
+export function isActivityContract(value) {
+    return typeof value === "object" && value !== null && value[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, into) {
+    for (const value of Object.values(mod)) {
+        if (isActivityContract(value))
+            into.set(value.name, value);
+    }
+}
+/** Every `ActivityStep` in a phase, including ones nested inside an `EffectStep`. */
+function activityStepsOf(steps) {
+    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) {
+    return typeof value === "object" && value !== null && value[STEP_OUTPUT_REF_BRAND] === true;
+}
+/**
+ * Does any prefix of `path` (a zod issue's `.path`) inside `obj` land on a
+ * step-output reference? A reference stands in for the whole value at its
+ * position, so an issue at or below it describes the placeholder, not the
+ * value it resolves to. "Below" matters for a whole-value reference in a
+ * record-typed arg (`inputs: step.out.json`, #3299): zod walks the
+ * reference's own keys, brand symbol included, and reports issues inside it.
+ */
+function pathCrossesStepOutputRef(obj, path) {
+    let current = obj;
+    for (const segment of path) {
+        if (current === null || typeof current !== "object")
+            return false;
+        current = current[segment];
+        if (isStepOutputRefValue(current))
+            return true;
+    }
+    return false;
+}
+/** Unwrap `ZodOptional`/`ZodNullable`/`ZodDefault` (and similar) down to the schema they wrap. */
+function unwrap(schema) {
+    let current = schema;
+    while (typeof current.unwrap === "function") {
+        current = current.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, path) {
+    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, path) {
+    let current = unwrap(schema);
+    for (const segment of path) {
+        if (!(current instanceof z.ZodObject))
+            return undefined;
+        const shape = current.shape;
+        if (!(segment in shape))
+            return undefined;
+        current = unwrap(shape[segment]);
+    }
+    return current;
+}
+export function primitiveKindOf(schema) {
+    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),
+ *  - a step's own `timeout` that is not a duration, or is longer than `MAX_STEP_TIMEOUT` (#2787),
+ *  - 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, contracts) {
+    const issues = [];
+    const phasesToWalk = [...config.phases, ...(config.onFailure ?? [])];
+    for (const phase of phasesToWalk) {
+        for (const step of activityStepsOf(phase.steps)) {
+            if (step.profile && !KNOWN_ACTIVITY_PROFILES.includes(step.profile)) {
+                issues.push({
+                    opName: config.name,
+                    phase: phase.name,
+                    fn: step.fn,
+                    message: `unknown profile "${step.profile}" (known: ${KNOWN_ACTIVITY_PROFILES.join(", ")})`,
+                });
+            }
+            if (step.timeout !== undefined) {
+                const problem = stepTimeoutProblem(step.timeout);
+                if (problem)
+                    issues.push({ opName: config.name, phase: phase.name, fn: step.fn, message: problem });
+            }
+            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, or above
+                    // it, is a placeholder object at build time, not the value it
+                    // will resolve to — so an args-schema issue there is a false
+                    // positive; OPS013 (`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 (pathCrossesStepOutputRef(step.args, issue.path))
+                        continue;
+                    // String(), not join(): a zod path can hold a symbol key, and
+                    // join() throws converting one (#3299).
+                    const path = issue.path.length > 0 ? issue.path.map((segment) => String(segment)).join(".") : "(args)";
+                    issues.push({ opName: config.name, phase: phase.name, fn: step.fn, message: `args.${path}: ${issue.message}` });
+                }
+            }
+            for (const attr of outcomeAttributesOf(step)) {
+                if (attr.from && contract.returns && !pathExistsInSchema(contract.returns, attr.from)) {
+                    issues.push({
+                        opName: config.name,
+                        phase: phase.name,
+                        fn: step.fn,
+                        message: `outcomeAttribute.from "${attr.from}" does not exist on "${step.fn}"'s declared return type`,
+                    });
+                }
+            }
+        }
+    }
+    return issues;
+}

package/dist/op/activity-failure.js

@@ -0,0 +1,31 @@
+/**
+ * A terminal activity failure.
+ *
+ * Some activities fail deterministically: an organizational policy violation
+ * (`policyGate`) or a cfn-guard finding (`guardValidate`) reads the same on the
+ * second attempt as on the first, so a retry only delays the report. Those
+ * activities used to raise an orchestrator SDK's non-retryable failure type,
+ * which put that SDK on the import path of every base activity. Core owns the
+ * base activities now (chant #2114), and depends on no runtime SDK — this is
+ * the same signal in a plain `Error`.
+ *
+ * `name` is the failure type, not the class name, so the local executor's
+ * `retry.nonRetryableErrorTypes` (which matches on `Error.name`) can name it in
+ * a profile. `type` and `nonRetryable` are kept alongside it because that is
+ * the shape callers and tests already read.
+ */
+export class NonRetryableActivityError extends Error {
+    constructor(message, 
+    /** Failure type, e.g. `"PolicyViolation"`. Also this error's `name`. */
+    type) {
+        super(message);
+        this.type = type;
+        /** Always true — present so a caller can branch without an `instanceof`. */
+        this.nonRetryable = true;
+        this.name = type;
+    }
+}
+/** Build a {@link NonRetryableActivityError} — a non-retryable failure with no SDK behind it. */
+export function nonRetryableFailure(message, type) {
+    return new NonRetryableActivityError(message, type);
+}

package/dist/op/activity-profiles.js

@@ -0,0 +1,129 @@
+/**
+ * Activity timeout and retry profiles.
+ *
+ * A profile is a named retry/timeout shape an Op step opts into
+ * (`activity("chantBuild", …, "fastIdempotent")`), so tuning lives in one table
+ * instead of inline at every call site. The six names cover the shapes infra
+ * steps actually take: fast idempotent work, long infra, K8s wait loops, a
+ * human gate, an Argo sync wait, and a deterministic policy check.
+ *
+ * These lived in a hosting lexicon, under its own prefixed name, until chant
+ * #2114 moved the base activities into core. Nothing about a timeout or a
+ * backoff coefficient belonged to that runtime, so the table came with them and
+ * lost the prefix. `heartbeatTimeout` did not come along: it configured a
+ * liveness protocol between a worker and a server, and no in-process step
+ * heartbeats to anything.
+ */
+import { parseDuration } from "./duration.js";
+/** Named activity profiles for common infrastructure step patterns. */
+export const ACTIVITY_PROFILES = {
+    /**
+     * Fast, idempotent operations: `chant build`, `kubectl apply` without `--wait`,
+     * fetching nameservers, reading cluster status.
+     */
+    fastIdempotent: {
+        timeout: "5m",
+        retry: { maximumAttempts: 3, initialInterval: "5s", backoffCoefficient: 2 },
+    },
+    /**
+     * Long-running infra: GKE cluster creation via Config Connector (~10-20 min),
+     * `kubectl apply --wait` for large resource sets, Helm installs.
+     */
+    longInfra: {
+        timeout: "20m",
+        retry: { maximumAttempts: 3, initialInterval: "30s", backoffCoefficient: 2 },
+    },
+    /**
+     * K8s wait loops: polling for StatefulSet rollout, ExternalDNS A-records,
+     * DNS propagation.
+     */
+    k8sWait: {
+        timeout: "15m",
+        // A terminal-state resource (waitForReady's ReadinessFailedError) will never
+        // become ready — fail fast instead of exhausting retries.
+        retry: {
+            maximumAttempts: 3,
+            initialInterval: "10s",
+            backoffCoefficient: 2,
+            nonRetryableErrorTypes: ["ReadinessFailedError"],
+        },
+    },
+    /**
+     * A command chant did not write and cannot know is safe to repeat (#2411).
+     *
+     * `shellCmd` is the escape hatch: its whole purpose is to run something
+     * outside the model, so nothing here can judge whether a second attempt is
+     * harmless or a second deployment. Every other activity carrying a retrying
+     * profile is one chant authored and knows the shape of.
+     *
+     * Twenty minutes, because a shell step is as likely to be a long build as a
+     * quick script, and one attempt, because retrying is the claim that needs
+     * evidence. An author who knows their command is idempotent names
+     * `fastIdempotent` or `longInfra` and gets retries back.
+     */
+    atMostOnce: {
+        timeout: "20m",
+        retry: { maximumAttempts: 1 },
+    },
+    /**
+     * Human-gate steps: waiting for an operator action (DNS delegation, approval).
+     * Very long timeout, single attempt — no retry on human-gate timeouts.
+     */
+    humanGate: {
+        timeout: "48h",
+        retry: { maximumAttempts: 1 },
+    },
+    /**
+     * Argo CD sync waits: poll an Application until `health=Healthy && sync=Synced`
+     * (`waitForArgoSync`). Long timeout for slow first syncs, cheap idempotent
+     * retries — re-polling is free. A terminal-unhealthy Application fails fast
+     * via `ArgoSyncFailedError` (non-retryable).
+     */
+    argoSync: {
+        timeout: "30m",
+        retry: {
+            maximumAttempts: 5,
+            initialInterval: "10s",
+            backoffCoefficient: 2,
+            maximumInterval: "1m",
+            nonRetryableErrorTypes: ["ArgoSyncFailedError"],
+        },
+    },
+    /**
+     * Organizational policy gate (`policyGate`): build the project and evaluate
+     * `lint.policies`. Deterministic — a violation is the same on every attempt —
+     * so a single attempt, short timeout, no retry.
+     */
+    policyCheck: {
+        timeout: "5m",
+        retry: { maximumAttempts: 1 },
+    },
+};
+/** Every profile name, as a runtime list (`KNOWN_ACTIVITY_PROFILES`'s source). */
+export const ACTIVITY_PROFILE_NAMES = Object.keys(ACTIVITY_PROFILES);
+/**
+ * The longest timeout one step may declare for itself (#2787): six hours, the
+ * ceiling hosted CI puts on a single job. A step's own `timeout` replaces its
+ * profile's and keeps the profile's retries, so a builder `shell` step can
+ * run 45 minutes on its one attempt. Anything that waits longer is waiting on
+ * someone, which is a gate's job (`humanGate`, 48 hours), not a step's.
+ */
+export const MAX_STEP_TIMEOUT = "6h";
+/** {@link MAX_STEP_TIMEOUT} in milliseconds. */
+export const MAX_STEP_TIMEOUT_MS = 6 * 3600000;
+/**
+ * Why `timeout` can't be a step's own timeout, or null when it can: it must
+ * be a duration such as `45m` or `1h30m`, more than zero, and at most
+ * {@link MAX_STEP_TIMEOUT}.
+ */
+export function stepTimeoutProblem(timeout) {
+    if (typeof timeout !== "string" || !/^(\d+(ms|s|m|h|d))+$/.test(timeout)) {
+        return `timeout ${JSON.stringify(timeout)} is not a duration such as "45m" or "1h30m"`;
+    }
+    const ms = parseDuration(timeout);
+    if (ms <= 0)
+        return `timeout "${timeout}" must be more than zero`;
+    if (ms > MAX_STEP_TIMEOUT_MS)
+        return `timeout "${timeout}" is longer than a step may run (${MAX_STEP_TIMEOUT}); a longer wait is a gate's`;
+    return null;
+}

package/dist/op/activity-registry.js

@@ -0,0 +1,105 @@
+/**
+ * Activity registry — resolves an Op step's `fn` name to a callable activity
+ * implementation for local execution.
+ *
+ * The base activities are core's own (`./activities`): plain async functions
+ * taking a single args object, with no workflow engine anywhere in the call
+ * path. They are imported statically, so `loadActivities([])` works in a
+ * project that has installed nothing but chant. Product-specific appliers stay
+ * in their owning lexicon (#809) and are pulled in dynamically per the
+ * project's configured lexicon list.
+ */
+import * as baseActivities from "./activities/index.js";
+import { ACTIVITY_PROFILES } from "./activity-profiles.js";
+import { importLexiconModule, importLexiconPackage } from "../lexicon-module.js";
+/**
+ * The export an activity module lists its fallback activities under: names it
+ * provides only when no other configured lexicon does (#3657). The sql
+ * lexicon's `receiptRead` / `receiptWrite` / `receiptStaleness` are the case:
+ * a project that uses only sql keeps its `effect()` receipts on its database
+ * server, and one that also configures aws or k8s keeps them in that
+ * lexicon's receipt row, whichever order `lexicons` lists them in.
+ */
+export const ACTIVITY_FALLBACKS_EXPORT = "ACTIVITY_FALLBACKS";
+/**
+ * Add every exported function from an activity module to `into`, keyed by
+ * name. A name the module lists in {@link ACTIVITY_FALLBACKS_EXPORT} is added
+ * only when nothing provides it yet; any other export replaces what is there,
+ * a fallback included.
+ */
+function collectActivities(mod, into) {
+    const listed = mod[ACTIVITY_FALLBACKS_EXPORT];
+    const fallbacks = new Set(Array.isArray(listed) ? listed.filter((n) => typeof n === "string") : []);
+    for (const [name, value] of Object.entries(mod)) {
+        if (typeof value !== "function")
+            continue;
+        if (fallbacks.has(name) && into.has(name))
+            continue;
+        into.set(name, value);
+    }
+}
+/**
+ * Build the activity map for local execution: core's base activities plus every
+ * activity module the project's configured lexicons contribute, keyed by export
+ * name (`shellCmd`, `kubectlApply`, `gcpApply`, …).
+ *
+ * Cloud-specific appliers live in their own lexicon (aws → `flociUp`/`flociDown`,
+ * gcp → `gcpApply`, azure → `azGroupEnsure`/`azGroupDelete`), so `lexicons` —
+ * the project's configured lexicon list — is consulted to pull those in. A
+ * lexicon that ships no `op/activities` module is skipped. A lexicon's
+ * fallback activities ({@link ACTIVITY_FALLBACKS_EXPORT}) give way to another
+ * lexicon's activity of the same name; otherwise a later lexicon's export
+ * replaces an earlier one's.
+ *
+ * Never throws: the base library is a static import, so there is no "no
+ * activities registered" state to report.
+ */
+export async function loadActivities(lexicons = []) {
+    const activities = new Map();
+    collectActivities(baseActivities, activities);
+    for (const name of lexicons) {
+        try {
+            // chant #2520 — a lexicon declared by module path has no subpath to
+            // import; its plugin's `activities()` member stands in for it.
+            const local = await importLexiconModule(name);
+            if (local !== undefined) {
+                const plugin = Object.values(local).find((v) => isActivityContributor(v) && v.name === name);
+                if (plugin)
+                    collectActivities(await plugin.activities(), activities);
+                continue;
+            }
+            const spec = `@intentius/chant-lexicon-${name}/op/activities`;
+            collectActivities((await importLexiconPackage(spec)), activities);
+        }
+        catch {
+            // Lexicon absent or contributes no activities — fine.
+        }
+    }
+    return activities;
+}
+function isActivityContributor(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.name === "string" &&
+        typeof value.activities === "function");
+}
+/**
+ * The built-in profile table. Kept async because it is awaited on the CLI's
+ * run path alongside {@link loadActivities}, and because a hosted runtime may
+ * one day resolve profiles from somewhere less immediate.
+ */
+export async function loadProfiles() {
+    return ACTIVITY_PROFILES;
+}
+/**
+ * Resolve a step's `fn` against the loaded activity map.
+ * Throws a clear error listing known names if the activity is missing.
+ */
+export function resolveActivity(activities, fn) {
+    const activity = activities.get(fn);
+    if (!activity) {
+        const known = [...activities.keys()].sort().join(", ");
+        throw new Error(`no activity named "${fn}" (known: ${known})`);
+    }
+    return activity;
+}

package/dist/op/activity-runtime.js

@@ -0,0 +1,28 @@
+/**
+ * Activity runtime helpers shared by every Op activity implementation, wherever
+ * it lives — the base activities in `./activities` and the product-specific
+ * appliers in the aws/gcp/azure/k8s/fly lexicons. Hosting them in core keeps a
+ * lexicon from depending on another lexicon just to sleep between polls.
+ */
+/**
+ * Sleep for `ms`, rejecting early if `signal` aborts. Polling activities use
+ * this between attempts so a local-executor timeout or Ctrl-C interrupts the
+ * wait instead of running it to completion.
+ */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error("aborted"));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error("aborted"));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}