@intentius/chant 0.1.14 → 0.1.16

package/src/lifecycle/change-set.ts

@@ -0,0 +1,172 @@
+/**
+ * Change set: a typed, read-only projection of a live diff.
+ *
+ * `chant lifecycle diff --live` computes a three-way comparison — declared now /
+ * last snapshot / live now — and prints it. `buildChangeSet` promotes that
+ * same signal into a classified create/update/delete/adopt/noop set that other
+ * tooling (reconcile, apply) can act on.
+ *
+ * Strictly read-only and pure: no I/O, no mutation. The classification reads
+ * ownership from the live marker only (populated downstream); until ownership
+ * exists, an undeclared live resource is `adopt`, never `delete`. The snapshot
+ * is evidence, never the basis for a mutation decision — it must never become
+ * load-bearing.
+ */
+import { diffLive, type AttributeChange, type DiffLiveInput } from "./live-diff";
+
+/**
+ * What the projection proposes for a single resource.
+ *
+ * - `create` — declared in source, absent from live.
+ * - `update` — declared and live, but live config drifted.
+ * - `delete` — a chant-owned resource that is live but no longer declared.
+ *   Only emitted once ownership is known (#121); never inferred from the
+ *   snapshot.
+ * - `adopt` — live but undeclared, ownership not established → a candidate to
+ *   pull back into source, never an auto-delete.
+ * - `noop` — declared and live with no drift, or already reconciled.
+ */
+export type ChangeAction = "create" | "update" | "delete" | "adopt" | "noop";
+
+/**
+ * Who answers "is this resource chant's?". `unknown` until a live ownership
+ * marker is queried (#120). The change set never escalates `unknown` to a
+ * delete.
+ */
+export type Ownership = "owned" | "foreign" | "unknown";
+
+export interface ChangeSetEntry {
+  /** chant entity name. */
+  name: string;
+  /** Resource type, when known from either side. */
+  type?: string;
+  action: ChangeAction;
+  /** The three-way evidence the classification was derived from. */
+  evidence: {
+    /** Present in the current build. */
+    declared: boolean;
+    /** Present in the last snapshot. */
+    inSnapshot: boolean;
+    /** Observed in the live system right now. */
+    live: boolean;
+  };
+  /** Attribute-level changes, for `update`. */
+  deltas?: AttributeChange[];
+  /** Live-marker ownership. Defaults to `unknown`. */
+  ownership: Ownership;
+}
+
+export interface ChangeSet {
+  env: string;
+  entries: ChangeSetEntry[];
+}
+
+/**
+ * Build a typed change set from the same inputs `diffLive` consumes.
+ *
+ * `create`/`update` are precise from declared-vs-live. `delete` is never
+ * emitted here — an undeclared live resource classifies as `adopt` until
+ * ownership is known.
+ */
+export function buildChangeSet(env: string, input: DiffLiveInput): ChangeSet {
+  const diff = diffLive(input);
+  const { declared, observedNow } = input;
+  const observedThen = input.observedThen ?? {};
+
+  const driftByName = new Map(
+    diff.driftedSinceSnapshot.map((d) => [d.name, d.changes] as const),
+  );
+
+  const names = new Set<string>([
+    ...declared,
+    ...Object.keys(observedNow),
+    ...Object.keys(observedThen),
+  ]);
+
+  const entries: ChangeSetEntry[] = [];
+  for (const name of names) {
+    const isDeclared = declared.has(name);
+    const live = Object.prototype.hasOwnProperty.call(observedNow, name);
+    const inSnapshot = Object.prototype.hasOwnProperty.call(observedThen, name);
+    const type = observedNow[name]?.type ?? observedThen[name]?.type;
+    const evidence = { declared: isDeclared, inSnapshot, live };
+
+    // Ownership comes from the LIVE marker only (carried on observedNow), never
+    // from the snapshot. This is the invariant that keeps the snapshot from
+    // becoming load-bearing: a mutation decision (delete) is never made from a
+    // record chant has to host.
+    const ownership: Ownership = observedNow[name]?.ownership ?? "unknown";
+
+    let action: ChangeAction;
+    let deltas: AttributeChange[] | undefined;
+
+    if (isDeclared && !live) {
+      // Declared in source, not in the cloud → create.
+      action = "create";
+    } else if (isDeclared && live) {
+      const drift = driftByName.get(name);
+      if (drift && drift.length > 0) {
+        action = "update";
+        deltas = drift;
+      } else {
+        action = "noop";
+      }
+    } else if (live) {
+      // Live but undeclared. Only a chant-owned orphan is a safe delete; a
+      // foreign or unknown orphan can be adopted but never auto-deleted.
+      action = ownership === "owned" ? "delete" : "adopt";
+    } else {
+      // Only in the snapshot: already gone, nothing to reconcile.
+      action = "noop";
+    }
+
+    entries.push({ name, type, action, evidence, deltas, ownership });
+  }
+
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  return { env, entries };
+}
+
+const ACTION_ORDER: ChangeAction[] = ["create", "update", "delete", "adopt", "noop"];
+
+/** Count entries per action. */
+export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
+  const counts: Record<ChangeAction, number> = {
+    create: 0,
+    update: 0,
+    delete: 0,
+    adopt: 0,
+    noop: 0,
+  };
+  for (const e of cs.entries) counts[e.action]++;
+  return counts;
+}
+
+/** Human-readable render of a change set. Pure — returns a string. */
+export function renderChangeSet(cs: ChangeSet): string {
+  const counts = summarize(cs);
+  const header = ACTION_ORDER.map((a) => `${counts[a]} ${a}`).join(", ");
+  const lines: string[] = [`Plan for ${cs.env}: ${header}`];
+
+  for (const action of ACTION_ORDER) {
+    const group = cs.entries.filter((e) => e.action === action);
+    if (group.length === 0) continue;
+    lines.push(`\n${action.toUpperCase()}:`);
+    for (const e of group) {
+      const own = e.ownership === "unknown" ? "" : ` [${e.ownership}]`;
+      lines.push(`  ${e.name}${e.type ? ` (${e.type})` : ""}${own}`);
+      for (const d of e.deltas ?? []) {
+        lines.push(`      ${d.path}: ${fmt(d.oldValue)} → ${fmt(d.newValue)}`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function fmt(v: unknown): string {
+  if (v === undefined) return "<unset>";
+  if (typeof v === "string") return v.length > 60 ? v.slice(0, 57) + "..." : v;
+  const json = JSON.stringify(v);
+  return json.length > 60 ? json.slice(0, 57) + "..." : json;
+}

package/src/{state → lifecycle}/git.test.ts

@@ -9,8 +9,8 @@ import {
   readEnvironmentSnapshots,
   listSnapshots,
   getHeadCommit,
-  pushState,
-  StaleStateBranchError,
+  pushLifecycle,
+  StaleLifecycleBranchError,
 } from "./git";
 
 function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
@@ -28,7 +28,7 @@ async function initRepo(dir: string): Promise<void> {
   git(["commit", "-q", "-m", "init"], dir);
 }
 
-describe("state/git", () => {
+describe("lifecycle/git", () => {
   test("writeSnapshot creates the orphan branch and writes JSON addressable by readSnapshot", async () => {
     await withTestDir(async (dir) => {
       await initRepo(dir);
@@ -135,7 +135,7 @@ describe("state/git", () => {
     const { clonePath, cleanup } = await setupClonePair();
     try {
       await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: clonePath });
-      const ok = await pushState({ cwd: clonePath });
+      const ok = await pushLifecycle({ cwd: clonePath });
       expect(ok).toBe(true);
     } finally {
       await cleanup();
@@ -146,18 +146,18 @@ describe("state/git", () => {
     const { clonePath, cleanup } = await setupClonePair();
     try {
       await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: clonePath });
-      expect(await pushState({ cwd: clonePath })).toBe(true);
+      expect(await pushLifecycle({ cwd: clonePath })).toBe(true);
 
       // Pull the remote ref into local remote-tracking, then commit + push again
-      git(["fetch", "-q", "origin", "+refs/heads/chant/state:refs/remotes/origin/chant/state"], clonePath);
+      git(["fetch", "-q", "origin", "+refs/heads/chant/lifecycle:refs/remotes/origin/chant/lifecycle"], clonePath);
       await writeSnapshot("prod", "aws", JSON.stringify({ a: 2 }), { cwd: clonePath });
-      expect(await pushState({ cwd: clonePath })).toBe(true);
+      expect(await pushLifecycle({ cwd: clonePath })).toBe(true);
     } finally {
       await cleanup();
     }
   });
 
-  test("concurrent write rejected: second push throws StaleStateBranchError", async () => {
+  test("concurrent write rejected: second push throws StaleLifecycleBranchError", async () => {
     // Simulate two concurrent operators by setting up two clones of the same remote.
     const { clonePath: cloneA, remotePath, cleanup } = await setupClonePair();
     const cloneB = join(import.meta.dirname ?? "/tmp", `chant-state-clone-b-${Date.now()}-${Math.random()}`);
@@ -168,13 +168,13 @@ describe("state/git", () => {
 
       // Operator A writes + pushes first.
       await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: cloneA });
-      expect(await pushState({ cwd: cloneA })).toBe(true);
+      expect(await pushLifecycle({ cwd: cloneA })).toBe(true);
 
-      // Operator B writes from the same baseline (chant/state doesn't exist
+      // Operator B writes from the same baseline (chant/lifecycle doesn't exist
       // on cloneB's remote-tracking yet) and tries to push — should fail
-      // with StaleStateBranchError because A's push moved the remote ref.
+      // with StaleLifecycleBranchError because A's push moved the remote ref.
       await writeSnapshot("staging", "gcp", JSON.stringify({ b: 2 }), { cwd: cloneB });
-      await expect(pushState({ cwd: cloneB })).rejects.toBeInstanceOf(StaleStateBranchError);
+      await expect(pushLifecycle({ cwd: cloneB })).rejects.toBeInstanceOf(StaleLifecycleBranchError);
     } finally {
       await cleanup();
       const { rm } = await import("node:fs/promises");
@@ -182,9 +182,9 @@ describe("state/git", () => {
     }
   });
 
-  test("StaleStateBranchError carries the expected SHA used as the lease", async () => {
-    const err = new StaleStateBranchError(null, "stale info: ...");
-    expect(err.name).toBe("StaleStateBranchError");
+  test("StaleLifecycleBranchError carries the expected SHA used as the lease", async () => {
+    const err = new StaleLifecycleBranchError(null, "stale info: ...");
+    expect(err.name).toBe("StaleLifecycleBranchError");
     expect(err.expected).toBeNull();
     expect(err.message).toContain("moved");
   });

package/src/{state → lifecycle}/git.ts

@@ -1,12 +1,12 @@
 /**
- * Git plumbing operations for the chant/state orphan branch.
+ * Git plumbing operations for the chant/lifecycle orphan branch.
  *
  * All operations use git plumbing commands — no checkout, no branch switching,
  * no working tree changes.
  */
 import { getRuntime } from "../runtime-adapter";
 
-const STATE_BRANCH = "chant/state";
+const STATE_BRANCH = "chant/lifecycle";
 
 /**
  * Write a state snapshot JSON to the orphan branch.
@@ -174,28 +174,28 @@ export async function listSnapshots(
 }
 
 /**
- * Thrown by pushState when the remote chant/state branch has moved since
+ * Thrown by pushLifecycle when the remote chant/lifecycle branch has moved since
  * the local snapshot was prepared — i.e. another snapshot for this or a
  * different env was pushed concurrently. The caller should fetch and retry.
  */
-export class StaleStateBranchError extends Error {
+export class StaleLifecycleBranchError extends Error {
   readonly expected: string | null;
   constructor(expected: string | null, stderr: string) {
     super(
-      "chant/state remote branch has moved since this run started — " +
+      "chant/lifecycle remote branch has moved since this run started — " +
       "another snapshot was pushed concurrently. " +
       `git stderr: ${stderr.trim()}`,
     );
-    this.name = "StaleStateBranchError";
+    this.name = "StaleLifecycleBranchError";
     this.expected = expected;
   }
 }
 
 /**
- * Look up the remote-tracking SHA for chant/state, if any. Returns null when
+ * Look up the remote-tracking SHA for chant/lifecycle, if any. Returns null when
  * the remote ref doesn't exist locally yet (e.g. first-ever snapshot).
  */
-export async function getRemoteStateBranchSha(
+export async function getRemoteLifecycleBranchSha(
   remote: string,
   opts?: { cwd?: string },
 ): Promise<string | null> {
@@ -209,13 +209,13 @@ export async function getRemoteStateBranchSha(
 /**
  * Push the state branch to remote with --force-with-lease.
  *
- * If the remote chant/state ref has advanced past the local remote-tracking
+ * If the remote chant/lifecycle ref has advanced past the local remote-tracking
  * SHA captured at the start of this push, the push is rejected and we throw
- * StaleStateBranchError so the caller can surface a recovery hint.
+ * StaleLifecycleBranchError so the caller can surface a recovery hint.
  *
  * Returns false (without throwing) only when no remote is configured at all.
  */
-export async function pushState(opts?: { cwd?: string }): Promise<boolean> {
+export async function pushLifecycle(opts?: { cwd?: string }): Promise<boolean> {
   const rt = getRuntime();
   const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
   if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
@@ -225,7 +225,7 @@ export async function pushState(opts?: { cwd?: string }): Promise<boolean> {
   // Capture the lease SHA — if null, the remote ref doesn't exist yet
   // (first-time push) and we send `--force-with-lease=ref:` (empty SHA),
   // which git interprets as "ref does not exist on remote".
-  const expected = await getRemoteStateBranchSha(remote, opts);
+  const expected = await getRemoteLifecycleBranchSha(remote, opts);
   const lease = `refs/heads/${STATE_BRANCH}:${expected ?? ""}`;
 
   const pushResult = await rt.spawn(
@@ -240,7 +240,7 @@ export async function pushState(opts?: { cwd?: string }): Promise<boolean> {
       stderr.includes("rejected") ||
       stderr.includes("non-fast-forward")
     ) {
-      throw new StaleStateBranchError(expected, stderr);
+      throw new StaleLifecycleBranchError(expected, stderr);
     }
     return false;
   }
@@ -250,7 +250,7 @@ export async function pushState(opts?: { cwd?: string }): Promise<boolean> {
 /**
  * Fetch the state branch from remote.
  */
-export async function fetchState(opts?: { cwd?: string }): Promise<boolean> {
+export async function fetchLifecycle(opts?: { cwd?: string }): Promise<boolean> {
   const rt = getRuntime();
   const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
   if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;

package/src/{state → lifecycle}/index.ts

@@ -2,3 +2,5 @@ export * from "./types";
 export * from "./git";
 export * from "./digest";
 export * from "./snapshot";
+export * from "./live-diff";
+export * from "./change-set";

package/src/{state → lifecycle}/snapshot.test.ts

@@ -4,12 +4,12 @@ import type { BuildResult } from "../build";
 
 const writeSnapshotMock = vi.fn();
 const getHeadCommitMock = vi.fn();
-const pushStateMock = vi.fn();
+const pushLifecycleMock = vi.fn();
 
 vi.mock("./git", () => ({
   writeSnapshot: (...args: unknown[]) => writeSnapshotMock(...args),
   getHeadCommit: () => getHeadCommitMock(),
-  pushState: () => pushStateMock(),
+  pushLifecycle: () => pushLifecycleMock(),
 }));
 
 const { takeSnapshot } = await import("./snapshot");
@@ -34,10 +34,10 @@ describe("takeSnapshot", () => {
   beforeEach(() => {
     writeSnapshotMock.mockReset();
     getHeadCommitMock.mockReset();
-    pushStateMock.mockReset();
+    pushLifecycleMock.mockReset();
     writeSnapshotMock.mockResolvedValue("commit-sha");
     getHeadCommitMock.mockResolvedValue("head-sha");
-    pushStateMock.mockResolvedValue(true);
+    pushLifecycleMock.mockResolvedValue(true);
   });
 
   test("happy path: writes snapshot per plugin with describeResources", async () => {
@@ -56,7 +56,7 @@ describe("takeSnapshot", () => {
       resources: { bucket: { type: "AWS::S3::Bucket", status: "CREATE_COMPLETE" } },
     });
     expect(writeSnapshotMock).toHaveBeenCalledTimes(1);
-    expect(pushStateMock).toHaveBeenCalledTimes(1);
+    expect(pushLifecycleMock).toHaveBeenCalledTimes(1);
   });
 
   test("plugin without describeResources is skipped", async () => {

package/src/{state → lifecycle}/snapshot.ts

@@ -1,13 +1,13 @@
 /**
  * Snapshot orchestration: queries plugins for deployed resource metadata,
- * assembles StateSnapshots, computes build digests, and writes to git.
+ * assembles LifecycleSnapshots, computes build digests, and writes to git.
  */
-import type { LexiconPlugin, ResourceMetadata, ArtifactMetadata } from "../lexicon";
+import type { ObservationLexicon, ResourceMetadata, ArtifactMetadata } from "../lexicon";
 import type { BuildResult } from "../build";
 import type { SerializerResult } from "../serializer";
-import type { StateSnapshot } from "./types";
+import type { LifecycleSnapshot } from "./types";
 import { computeBuildDigest } from "./digest";
-import { writeSnapshot, getHeadCommit, pushState } from "./git";
+import { writeSnapshot, getHeadCommit, pushLifecycle } from "./git";
 import { sortedJsonReplacer } from "../utils";
 
 /** Patterns in attribute names that suggest sensitive data. */
@@ -71,7 +71,7 @@ function validateResources(
 }
 
 export interface TakeSnapshotResult {
-  snapshots: StateSnapshot[];
+  snapshots: LifecycleSnapshot[];
   commit: string;
   warnings: string[];
   errors: string[];
@@ -82,13 +82,13 @@ export interface TakeSnapshotResult {
  */
 export async function takeSnapshot(
   environment: string,
-  plugins: LexiconPlugin[],
+  plugins: ObservationLexicon[],
   buildResult: BuildResult,
   opts?: { cwd?: string },
 ): Promise<TakeSnapshotResult> {
   const warnings: string[] = [];
   const errors: string[] = [];
-  const snapshots: StateSnapshot[] = [];
+  const snapshots: LifecycleSnapshot[] = [];
 
   const headCommit = await getHeadCommit(opts);
   const timestamp = new Date().toISOString();
@@ -155,7 +155,7 @@ export async function takeSnapshot(
         continue;
       }
 
-      const snapshot: StateSnapshot = {
+      const snapshot: LifecycleSnapshot = {
         lexicon: plugin.name,
         environment,
         commit: headCommit,
@@ -187,7 +187,7 @@ export async function takeSnapshot(
 
   // Push to remote
   if (snapshots.length > 0) {
-    await pushState(opts);
+    await pushLifecycle(opts);
   }
 
   return {

package/src/{state → lifecycle}/types.ts

@@ -5,7 +5,7 @@ export type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
 /**
  * State snapshot for a single lexicon in an environment.
  */
-export interface StateSnapshot {
+export interface LifecycleSnapshot {
   lexicon: string;
   environment: string;
   /** Main branch commit this corresponds to */

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

@@ -0,0 +1,59 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { loadActivities, resolveActivity, type ActivityFn } from "./activity-registry";
+
+describe("loadActivities", () => {
+  afterEach(() => {
+    vi.resetModules();
+    vi.doUnmock("@intentius/chant-lexicon-temporal/op/activities");
+  });
+
+  test("loads the lexicon activity library keyed by export name", async () => {
+    const activities = await loadActivities();
+    // Real export names from lexicons/temporal/src/op/activities.
+    expect(activities.has("shellCmd")).toBe(true);
+    expect(activities.has("chantBuild")).toBe(true);
+    expect(activities.has("kubectlApply")).toBe(true);
+    expect(activities.has("lifecycleDiff")).toBe(true);
+    expect(typeof activities.get("shellCmd")).toBe("function");
+  });
+
+  test("throws a friendly error when the lexicon is not installed", async () => {
+    vi.resetModules();
+    vi.doMock("@intentius/chant-lexicon-temporal/op/activities", () => {
+      throw new Error("Cannot find module");
+    });
+    const { loadActivities: fresh } = await import("./activity-registry");
+    await expect(fresh()).rejects.toThrow(
+      "no activities registered — install `@intentius/chant-lexicon-temporal`",
+    );
+  });
+});
+
+describe("resolveActivity", () => {
+  test("resolves a known activity by name", () => {
+    const fn: ActivityFn = async () => "ok";
+    const map = new Map<string, ActivityFn>([["shellCmd", fn]]);
+    expect(resolveActivity(map, "shellCmd")).toBe(fn);
+  });
+
+  test("throws listing known names for an unknown fn", () => {
+    const map = new Map<string, ActivityFn>([
+      ["shellCmd", async () => undefined],
+      ["chantBuild", async () => undefined],
+    ]);
+    expect(() => resolveActivity(map, "nope")).toThrow(
+      'no activity named "nope" (known: chantBuild, shellCmd)',
+    );
+  });
+});
+
+describe("loadActivities — heartbeat-shim safety", () => {
+  test("the activity library loads without @temporalio/activity installed", async () => {
+    // kubectlApply/helmInstall/waitForStack/gitlabPipeline heartbeat via the
+    // lazy shim; if the shim statically required the SDK, this import would
+    // throw (the SDK is not installed in this environment).
+    const activities = await loadActivities();
+    expect(activities.has("kubectlApply")).toBe(true);
+    expect(activities.has("waitForStack")).toBe(true);
+  });
+});

package/src/op/activity-registry.ts

@@ -0,0 +1,98 @@
+/**
+ * Activity registry — resolves an Op step's `fn` name to a callable activity
+ * implementation for local execution.
+ *
+ * Activities live in the Temporal lexicon (`@intentius/chant-lexicon-temporal`)
+ * but are plain async functions taking a single args object — Temporal-free to
+ * call. Local mode loads them by name instead of registering them with a worker.
+ */
+
+/**
+ * An activity is an async function taking a single args object and an optional
+ * `AbortSignal`. Local execution passes a signal that fires on timeout or
+ * Ctrl-C so the activity can kill in-flight child processes; the Temporal
+ * worker invokes activities with args only (cancellation comes from its own
+ * `Context`), so the signal is always optional.
+ */
+export type ActivityFn = (args: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>;
+
+/**
+ * Dynamically import the Temporal lexicon's activity library and return a map
+ * of every exported function keyed by its export name (`shellCmd`, `chantBuild`,
+ * `kubectlApply`, …).
+ *
+ * Throws a friendly error if the lexicon is not installed — local execution
+ * needs the activity implementations even though it never starts a worker.
+ */
+export async function loadActivities(): Promise<Map<string, ActivityFn>> {
+  let mod: Record<string, unknown>;
+  try {
+    // Variable specifier so tsc does not statically resolve the optional dep.
+    const spec = "@intentius/chant-lexicon-temporal/op/activities";
+    mod = (await import(spec)) as Record<string, unknown>;
+  } catch {
+    throw new Error(
+      "no activities registered — install `@intentius/chant-lexicon-temporal`",
+    );
+  }
+
+  const activities = new Map<string, ActivityFn>();
+  for (const [name, value] of Object.entries(mod)) {
+    if (typeof value === "function") {
+      activities.set(name, value as ActivityFn);
+    }
+  }
+  return activities;
+}
+
+/** Structural shape of a TEMPORAL_ACTIVITY_PROFILES entry (timeout + retry). */
+export interface ActivityProfile {
+  startToCloseTimeout?: string;
+  heartbeatTimeout?: string;
+  retry?: {
+    initialInterval?: string;
+    backoffCoefficient?: number;
+    maximumAttempts?: number;
+    maximumInterval?: string;
+    /** Error names (`Error.name`) that should fail immediately without retry. */
+    nonRetryableErrorTypes?: string[];
+  };
+}
+
+/**
+ * Dynamically import the lexicon's `TEMPORAL_ACTIVITY_PROFILES` (pure data, no
+ * Temporal SDK). Returns an empty record if the lexicon is absent — the
+ * executor then falls back to built-in defaults per step.
+ *
+ * Imports the lexicon's `/config` entry, not its root index. `/config` is a
+ * side-effect-free data module; the root index pulls in the plugin, serializer,
+ * composites, and re-exported Op machinery, any of which could throw on load
+ * and make this silently return `{}` — which would drop every profiled step to
+ * the 5-minute default while the Temporal path (reading the same table) kept the
+ * declared timeout. Importing the narrow module keeps the two executors agreed.
+ */
+export async function loadProfiles(): Promise<Record<string, ActivityProfile>> {
+  try {
+    const spec = "@intentius/chant-lexicon-temporal/config";
+    const mod = (await import(spec)) as { TEMPORAL_ACTIVITY_PROFILES?: Record<string, ActivityProfile> };
+    return mod.TEMPORAL_ACTIVITY_PROFILES ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 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: Map<string, ActivityFn>,
+  fn: string,
+): ActivityFn {
+  const activity = activities.get(fn);
+  if (!activity) {
+    const known = [...activities.keys()].sort().join(", ");
+    throw new Error(`no activity named "${fn}" (known: ${known})`);
+  }
+  return activity;
+}