@intentius/chant 0.28.0 → 0.30.0

package/src/live-endpoint.ts

@@ -0,0 +1,148 @@
+/**
+ * chant #1166 — let a declared `environment` carry its own endpoint so
+ * `--live --env <name>` is self-sufficient.
+ *
+ * The bug this closes: `chant graph --live --env floci` (and `lifecycle
+ * diff`/`plan`) observe a stack by shelling out through each lexicon's
+ * `describeResources()`. For AWS that shell-out honors the ambient
+ * `AWS_ENDPOINT_URL` env var — when a project's `floci` environment is a local
+ * emulator (`http://localhost:4566`) but the invoking shell never exported
+ * that var, the AWS CLI silently targets real AWS instead. The stack named
+ * after the environment doesn't exist there, so `describeResources` hits its
+ * `stackDoesNotExist` branch and returns an empty, unremarkable "nothing is
+ * deployed" — indistinguishable from the truthful answer. This cost real
+ * debugging time validating #1162's live overlay: the observation code was
+ * right, the manual repro just never set the var.
+ *
+ * The fix: `environments` in `chant.config.ts` can name an endpoint per
+ * environment (`config.ts`'s `EnvironmentDeclaration`), and {@link
+ * applyLiveEndpoint} injects it into the ambient env var each observing
+ * lexicon's CLI shell-out actually reads — but only for a var that isn't
+ * already set. Ambient always wins: a shell that already exports
+ * `AWS_ENDPOINT_URL` sees no change in behavior.
+ *
+ * Audited (#1166) which lexicons have an ambient-env-var endpoint knob at
+ * all, since that's the specific footgun — a lexicon whose environment
+ * binding is resolved from `chant.config` itself (not an ambient var) has
+ * nothing to inject here:
+ *
+ *   - **aws**  — `AWS_ENDPOINT_URL`, read directly by
+ *     `lexicons/aws/src/components/cloud-executor.ts` / `plugin.ts` before
+ *     every `aws …` shell-out (`applyAwsEndpoint`/`applyAwsEndpointArgv`).
+ *   - **fly**  — `FLY_FLAPS_BASE_URL`, read by `resolveEndpoint()` in
+ *     `lexicons/fly/src/op/activities/fly-apply.ts`, the same seam
+ *     `describeResources` (`../describe-resources.ts`) calls through.
+ *   - **gcp**, **k8s** — resolve their live target from `chant.config` itself
+ *     (`k8s.profiles.<env>.context` via `resolveClusterTarget`,
+ *     `packages/core/src/kubectl-context.ts`), not an ambient var. Nothing to
+ *     inject: the config *is* the binding already.
+ *   - **azure** — resolves via the `az` CLI's own logged-in
+ *     subscription/session context; no ambient endpoint var exists to miss.
+ *   - **temporal** — resolves its connection from `temporal.profiles.<env>`
+ *     (`resolveProfile`, `lexicons/temporal/src/describe-resources.ts`), the
+ *     same "config is the binding" shape as k8s/gcp.
+ */
+
+import { environmentEndpoint, type EnvironmentDeclaration } from "./config";
+
+/**
+ * Per-lexicon ambient env var a `--live` read honors for its endpoint. Only
+ * lexicons with a genuine ambient-var footgun are listed — see the module doc
+ * for the full audit (gcp/k8s/azure/temporal resolve their target from
+ * `chant.config` instead, so they have nothing to inject).
+ */
+export const LEXICON_ENDPOINT_ENV_VAR: Record<string, string> = {
+  aws: "AWS_ENDPOINT_URL",
+  fly: "FLY_FLAPS_BASE_URL",
+};
+
+/** Result of {@link applyLiveEndpoint} — always call `restore()`, even when nothing was applied (it is then a no-op). */
+export interface AppliedEndpoint {
+  /**
+   * One line describing what happened, or `undefined` when the environment
+   * declares no endpoint at all (nothing to say). Present whether the
+   * declared endpoint was applied OR an ambient var already won — #1166's
+   * "no silent anything" stance: an operator should never have to guess which
+   * target a `--live` read actually used.
+   */
+  notice?: string;
+  /** Undo whatever ambient env vars this call set. Always safe to call. */
+  restore: () => void;
+}
+
+/**
+ * Resolve `environment`'s declared endpoint (if any) from `config.environments`
+ * and apply it to the ambient env var of every lexicon in `lexicons` that has
+ * one ({@link LEXICON_ENDPOINT_ENV_VAR}) — but only when that var isn't
+ * already set. Ambient always wins (#1166): behavior for a shell that already
+ * exports `AWS_ENDPOINT_URL` is unchanged.
+ *
+ * Call before a `--live` describe/enrich pass; `restore()` in a `finally` so
+ * the injected value never leaks into a later invocation in the same process
+ * (tests, or a long-lived host like the MCP server).
+ */
+export function applyLiveEndpoint(
+  environments: EnvironmentDeclaration[] | undefined,
+  environment: string,
+  lexicons: readonly string[],
+  env: NodeJS.ProcessEnv = process.env,
+): AppliedEndpoint {
+  const endpoint = environmentEndpoint(environments, environment);
+  if (!endpoint) return { restore: () => {} };
+
+  const applied: string[] = [];
+  const overridden: string[] = [];
+  const seen = new Set<string>(); // a var shared by two lexicons is only reported once
+  for (const lexicon of lexicons) {
+    const varName = LEXICON_ENDPOINT_ENV_VAR[lexicon];
+    if (!varName || seen.has(varName)) continue;
+    seen.add(varName);
+    if (env[varName]) {
+      overridden.push(varName);
+      continue;
+    }
+    env[varName] = endpoint;
+    applied.push(varName);
+  }
+
+  const notices: string[] = [];
+  if (applied.length > 0) {
+    notices.push(
+      `environment "${environment}" declares endpoint ${endpoint} — applied to ${applied.join(", ")} for this read`,
+    );
+  }
+  if (overridden.length > 0) {
+    notices.push(
+      `ambient ${overridden.join(", ")} already set — keeping it over environment "${environment}"'s declared endpoint (${endpoint})`,
+    );
+  }
+
+  return {
+    notice: notices.length > 0 ? notices.join("; ") : undefined,
+    restore: () => {
+      for (const varName of applied) delete env[varName];
+    },
+  };
+}
+
+/**
+ * #1166 acceptance: when a `--live` describe comes back with zero resources
+ * for a lexicon that had declared entities to look for, and nothing was
+ * already reported NOT-OBSERVED (#1089) either, that is either "genuinely
+ * nothing is deployed yet" or a misconfigured endpoint/credentials — the two
+ * are visually identical, so a caller must say so rather than stay quiet.
+ * Returns `undefined` when there is nothing to declare (no declared entities
+ * to have asked about, or the emptiness is already explained by #1089's
+ * `unobserved`).
+ */
+export function zeroResourcesWarning(
+  lexicon: string,
+  environment: string,
+  declaredCount: number,
+  observed: { resources: Record<string, unknown>; unobserved: Record<string, unknown> },
+): string | undefined {
+  if (declaredCount === 0) return undefined;
+  if (Object.keys(observed.resources).length > 0) return undefined;
+  if (Object.keys(observed.unobserved).length > 0) return undefined;
+  return `${lexicon}: 0 live resources for env "${environment}" (${declaredCount} declared) — check the endpoint/credentials`;
+}

package/src/observation.test.ts

@@ -0,0 +1,96 @@
+/**
+ * The observation contract itself (#1089) — the normalizer, the envelope
+ * discriminant, and the multi-stack merge.
+ */
+import { describe, test, expect } from "vitest";
+import {
+  UNOBSERVED_REASONS,
+  formatUnobserved,
+  isObservationResult,
+  isUnobservedReason,
+  mergeObservations,
+  normalizeObservation,
+  observation,
+  unobservedAll,
+  unobservedReasonText,
+} from "./observation";
+import type { ResourceMetadata } from "./lexicon";
+
+const meta = (over: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
+  type: "Fake::Resource",
+  status: "OK",
+  ...over,
+});
+
+describe("normalizeObservation", () => {
+  test("a bare map means 'I looked at everything'", () => {
+    expect(normalizeObservation({ a: meta() })).toEqual({ resources: { a: meta() }, unobserved: {} });
+  });
+
+  test("the envelope carries both halves", () => {
+    const value = observation({ a: meta() }, { b: { reason: "read-failed" } });
+    expect(normalizeObservation(value)).toEqual({
+      resources: { a: meta() },
+      unobserved: { b: { reason: "read-failed" } },
+    });
+  });
+
+  test("undefined normalizes to two empty maps", () => {
+    expect(normalizeObservation(undefined)).toEqual({ resources: {}, unobserved: {} });
+  });
+
+  test("an entity literally named `observation` cannot be mistaken for the envelope", () => {
+    const bare = { observation: meta({ type: "Odd::Name" }) };
+    expect(isObservationResult(bare)).toBe(false);
+    expect(normalizeObservation(bare).resources.observation.type).toBe("Odd::Name");
+  });
+
+  test("the envelope omits an empty unobserved map", () => {
+    expect(observation({ a: meta() }, {})).toEqual({ observation: "v1", resources: { a: meta() } });
+  });
+});
+
+describe("unobservedAll", () => {
+  test("marks every named entity with one reason, carrying declared types", () => {
+    const entities = new Map([["a", { entityType: "AWS::S3::Bucket" }]]);
+    expect(unobservedAll(["a", "b"], "no-credentials", "token expired", entities)).toEqual({
+      a: { reason: "no-credentials", type: "AWS::S3::Bucket", detail: "token expired" },
+      b: { reason: "no-credentials", detail: "token expired" },
+    });
+  });
+});
+
+describe("mergeObservations (multi-stack)", () => {
+  test("present beats not-observed beats absent", () => {
+    const merged = mergeObservations([
+      { resources: {}, unobserved: { a: { reason: "read-failed" }, b: { reason: "no-binding" } } },
+      { resources: { a: meta() }, unobserved: {} },
+    ]);
+    expect(Object.keys(merged.resources)).toEqual(["a"]);
+    expect(Object.keys(merged.unobserved)).toEqual(["b"]);
+  });
+
+  test("an entity nobody looked for in any stack stays absent", () => {
+    const merged = mergeObservations([
+      { resources: { a: meta() }, unobserved: {} },
+      { resources: { b: meta() }, unobserved: {} },
+    ]);
+    expect(merged.unobserved).toEqual({});
+  });
+});
+
+describe("reason totality", () => {
+  test("every reason has human text and passes the guard", () => {
+    for (const reason of UNOBSERVED_REASONS) {
+      expect(isUnobservedReason(reason)).toBe(true);
+      expect(unobservedReasonText(reason).length).toBeGreaterThan(0);
+    }
+    expect(isUnobservedReason("made-up")).toBe(false);
+  });
+
+  test("formatUnobserved names the entity, the type and the detail", () => {
+    expect(
+      formatUnobserved("widget", { type: "K8s::X::Widget", reason: "unsupported-kind", detail: "no mapping" }),
+    ).toBe("widget (K8s::X::Widget) — no reader for this resource kind: no mapping");
+  });
+});

package/src/observation.ts

@@ -0,0 +1,213 @@
+/**
+ * The observation contract (#1089) — what a lexicon's `describeResources()`
+ * is allowed to mean.
+ *
+ * Before this module there were two ways for an observation to return nothing
+ * for a declared entity and no way to tell them apart:
+ *
+ *   1. The provider was asked and said the resource does not exist.
+ *   2. The lexicon never looked — no reader for that kind, the read errored,
+ *      no credentials, no cluster/subscription binding.
+ *
+ * Both arrived at the change set as "absent", and absent + declared classifies
+ * as `create`. So `chant lifecycle plan` proposed creating a Kubernetes CRD
+ * that already existed in the cluster, with nothing in the plan to say the tool
+ * had simply not looked (a warn on stderr is not a signal in a change set).
+ *
+ * The contract is a tri-state, per declared entity:
+ *
+ *   - **OBSERVED-PRESENT** — a key in `resources`. The provider returned it.
+ *   - **OBSERVED-ABSENT** — in neither map. The lexicon looked and the provider
+ *     reported it missing. This is the only shape that may become a `create`.
+ *   - **NOT-OBSERVED** — a key in `unobserved`, carrying a total
+ *     {@link UnobservedReason}. Never a `create`, never a `delete`; consumers
+ *     surface it and stop.
+ *
+ * Compatibility: `describeResources()` may still return the bare
+ * `name → ResourceMetadata` map it always did — that means "everything I was
+ * asked about, I looked at" and normalizes to an empty `unobserved`. Reporting
+ * NOT-OBSERVED requires the explicitly versioned {@link ObservationResult}
+ * envelope, which is discriminated by its literal `observation: "v1"` field (a
+ * bare map's value at any key is a `ResourceMetadata` object, never that
+ * string, so the two shapes can never be confused).
+ */
+
+import type { ResourceMetadata } from "./lexicon";
+
+/**
+ * Why a declared entity was not observed. Total: a lexicon that cannot observe
+ * an entity must pick one of these, and consumers may switch exhaustively.
+ *
+ * - `read-failed` — the provider was reached and the read errored (a non-zero
+ *   CLI exit, a 5xx, an unparseable response).
+ * - `no-credentials` — no usable credentials/authorization for the target.
+ * - `no-binding` — the environment resolves to no concrete target (no kubectl
+ *   context, no subscription, no stack, no endpoint).
+ * - `unsupported-kind` — the lexicon has no reader for this entity type (the
+ *   K8s CRD case, Azure's nested ARM types). The resource may well exist.
+ * - `filtered` — the entity was reached but withheld by a caller-requested
+ *   filter (`owned: true` against a resource carrying no chant marker). The
+ *   result deliberately says nothing about it, which is still not absence: a
+ *   declared resource that exists but is foreign must not classify as `create`.
+ */
+export type UnobservedReason =
+  | "read-failed"
+  | "no-credentials"
+  | "no-binding"
+  | "unsupported-kind"
+  | "filtered";
+
+/** Every legal {@link UnobservedReason}, for validation and conformance checks. */
+export const UNOBSERVED_REASONS: readonly UnobservedReason[] = [
+  "read-failed",
+  "no-credentials",
+  "no-binding",
+  "unsupported-kind",
+  "filtered",
+];
+
+/** True when `value` is a legal {@link UnobservedReason}. */
+export function isUnobservedReason(value: unknown): value is UnobservedReason {
+  return typeof value === "string" && (UNOBSERVED_REASONS as readonly string[]).includes(value);
+}
+
+/** One declared entity the lexicon could not observe, and why. */
+export interface UnobservedEntity {
+  /** Declared entity type, when the lexicon knows it (it usually does — the entity is declared). */
+  type?: string;
+  /** Total verdict. */
+  reason: UnobservedReason;
+  /** Human-readable detail: the command that failed, the missing binding key, the unsupported kind. */
+  detail?: string;
+}
+
+/**
+ * The observation envelope — a `describeResources()` return value that can say
+ * "I did not look at this one". Explicitly versioned: `observation: "v1"`.
+ */
+export interface ObservationResult {
+  /** Discriminant + wire version. Distinguishes the envelope from the bare `name → ResourceMetadata` map. */
+  readonly observation: "v1";
+  /** OBSERVED-PRESENT, keyed by chant entity name. */
+  resources: Record<string, ResourceMetadata>;
+  /** NOT-OBSERVED, keyed by chant entity name. Omit or leave empty when everything asked about was looked at. */
+  unobserved?: Record<string, UnobservedEntity>;
+}
+
+/**
+ * What `describeResources()` may return: the bare map (pre-#1089, still valid —
+ * "I looked at everything") or the {@link ObservationResult} envelope.
+ */
+export type DescribeResourcesResult = Record<string, ResourceMetadata> | ObservationResult;
+
+/** Normalized form every consumer works with. Both maps always present. */
+export interface NormalizedObservation {
+  resources: Record<string, ResourceMetadata>;
+  unobserved: Record<string, UnobservedEntity>;
+}
+
+/** True when `value` is the versioned {@link ObservationResult} envelope. */
+export function isObservationResult(value: unknown): value is ObservationResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { observation?: unknown }).observation === "v1"
+  );
+}
+
+/**
+ * Build an {@link ObservationResult}. Lexicons use this rather than writing the
+ * discriminant by hand.
+ */
+export function observation(
+  resources: Record<string, ResourceMetadata>,
+  unobserved?: Record<string, UnobservedEntity>,
+): ObservationResult {
+  return {
+    observation: "v1",
+    resources,
+    ...(unobserved && Object.keys(unobserved).length > 0 ? { unobserved } : {}),
+  };
+}
+
+/**
+ * Normalize either accepted return shape. `undefined` (a lexicon that returned
+ * nothing at all) normalizes to two empty maps — which reads as "everything was
+ * observed absent", so callers that mean "the read failed" must say so with
+ * {@link unobservedAll} rather than returning nothing.
+ */
+export function normalizeObservation(value: DescribeResourcesResult | undefined): NormalizedObservation {
+  if (!value) return { resources: {}, unobserved: {} };
+  if (isObservationResult(value)) {
+    return { resources: value.resources ?? {}, unobserved: value.unobserved ?? {} };
+  }
+  return { resources: value, unobserved: {} };
+}
+
+/**
+ * Mark every named entity NOT-OBSERVED with one reason — the whole-lexicon
+ * failure case (the provider CLI is missing, the cluster binding refused, the
+ * credentials are gone). Core applies this when `describeResources()` throws,
+ * so a thrown read degrades to an honest "did not look" for each declared
+ * entity instead of an empty map that classifies as N creates.
+ */
+export function unobservedAll(
+  names: Iterable<string>,
+  reason: UnobservedReason,
+  detail?: string,
+  types?: Map<string, { entityType: string }> | Record<string, string>,
+): Record<string, UnobservedEntity> {
+  const typeOf = (name: string): string | undefined => {
+    if (!types) return undefined;
+    if (types instanceof Map) return types.get(name)?.entityType;
+    return types[name];
+  };
+  const out: Record<string, UnobservedEntity> = {};
+  for (const name of names) {
+    const type = typeOf(name);
+    out[name] = { reason, ...(type ? { type } : {}), ...(detail ? { detail } : {}) };
+  }
+  return out;
+}
+
+/**
+ * Union several observations of the same lexicon (the multi-stack read, where
+ * `describeResources` runs once per stack). Precedence is
+ * present > not-observed > absent: a resource found in any stack is present; an
+ * entity nobody could look at stays not-observed; an entity every reader looked
+ * for and did not find is absent.
+ */
+export function mergeObservations(parts: Iterable<NormalizedObservation>): NormalizedObservation {
+  const resources: Record<string, ResourceMetadata> = {};
+  const unobserved: Record<string, UnobservedEntity> = {};
+  for (const part of parts) {
+    Object.assign(resources, part.resources);
+    Object.assign(unobserved, part.unobserved);
+  }
+  // Present wins: a stack that could not be read does not un-observe a resource
+  // another stack returned.
+  for (const name of Object.keys(resources)) delete unobserved[name];
+  return { resources, unobserved };
+}
+
+/** One-line human phrasing of a reason, for CLI output. */
+export function unobservedReasonText(reason: UnobservedReason): string {
+  switch (reason) {
+    case "read-failed":
+      return "read failed";
+    case "no-credentials":
+      return "no credentials";
+    case "no-binding":
+      return "no binding for this environment";
+    case "unsupported-kind":
+      return "no reader for this resource kind";
+    case "filtered":
+      return "withheld by the --owned filter";
+  }
+}
+
+/** `name — reason (detail)`, the shared rendering for CLI and plan output. */
+export function formatUnobserved(name: string, entry: UnobservedEntity): string {
+  const base = `${name}${entry.type ? ` (${entry.type})` : ""} — ${unobservedReasonText(entry.reason)}`;
+  return entry.detail ? `${base}: ${entry.detail}` : base;
+}

package/src/stack-output.test.ts

@@ -97,6 +97,61 @@ describe("stackOutput", () => {
     expect(out.lexicon).toBe("aws");
     vi.resetModules();
   });
+
+  // chant #1152 — a CloudFormation Parameter carries no attributes at all, so
+  // `Ref(param)` (an intrinsic wrapping the Parameter Declarable directly, not
+  // one of its attributes) could never contain a nested AttrRef for the old
+  // AttrRef-only anchor search to find. Before the fix that meant `firstAttrRef`
+  // always came back empty for this shape and the output's `lexicon` silently
+  // became `"unknown"` — not a thrown error (a Parameter-wrapping `Ref` already
+  // carries the `Intrinsic` marker, so the input-validation guard always
+  // accepted it), but `"unknown"` isn't any real lexicon's partition, so the
+  // output was silently dropped from every serializer's `Outputs` section.
+  const param: Declarable = {
+    lexicon: "aws",
+    entityType: "AWS::CloudFormation::Parameter",
+    [DECLARABLE_MARKER]: true,
+  };
+
+  test("derives lexicon from a Declarable referenced directly by a wrapping intrinsic (Ref(param))", () => {
+    const ref = {
+      [INTRINSIC_MARKER]: true as const,
+      target: param,
+      toJSON: () => ({ Ref: "environment" }),
+    };
+
+    const out = stackOutput(ref, { exportName: "EnvironmentName" });
+    expect(out.lexicon).toBe("aws");
+    expect(out.sourceRef).toBe(ref);
+    expect(out.exportName).toBe("EnvironmentName");
+  });
+
+  test("derives lexicon from a Declarable referenced directly, nested inside a further intrinsic (Sub interpolating Ref(param))", () => {
+    const ref = {
+      [INTRINSIC_MARKER]: true as const,
+      target: param,
+      toJSON: () => ({ Ref: "environment" }),
+    };
+    const sub = {
+      [INTRINSIC_MARKER]: true as const,
+      values: [ref],
+      toJSON: () => ({ "Fn::Sub": "env-${environment}" }),
+    };
+
+    const out = stackOutput(sub);
+    expect(out.lexicon).toBe("aws");
+  });
+
+  test("an explicit options.lexicon still wins over a Declarable-derived anchor", () => {
+    const ref = {
+      [INTRINSIC_MARKER]: true as const,
+      target: param,
+      toJSON: () => ({ Ref: "environment" }),
+    };
+
+    const out = stackOutput(ref, { lexicon: "gcp" });
+    expect(out.lexicon).toBe("gcp");
+  });
 });
 
 describe("isStackOutput", () => {

package/src/stack-output.ts

@@ -6,7 +6,7 @@
  * it via `nestedStack().outputs.name`.
  */
 
-import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+import { DECLARABLE_MARKER, isDeclarable, type Declarable } from "./declarable";
 import { AttrRef } from "./attrref";
 import { isIntrinsic, type Intrinsic } from "./intrinsic";
 import { isAttrRefLike } from "./utils";
@@ -35,25 +35,47 @@ export interface StackOutput extends Declarable {
   readonly exportName?: string;
 }
 
-/** Find the first AttrRef anywhere inside a value (walking intrinsics/objects/
- * arrays), so a wrapping intrinsic can still borrow its parent's lexicon.
- * Duck-type, not `instanceof` (chant #1137): a lexicon built against a
- * separate copy of `@intentius/chant` produces AttrRefs that fail
- * `instanceof AttrRef` here but carry the same shape — missing one would
- * make the walk recurse into the AttrRef's own (unhelpful) fields instead
- * of stopping on it, silently failing to find the anchor. */
-function firstAttrRef(value: unknown, seen = new Set<unknown>()): AttrRef | undefined {
+/** What a wrapping intrinsic's lexicon gets derived from: either a nested
+ * AttrRef (borrow its parent's `.lexicon`) or a Declarable referenced
+ * directly (use its own `.lexicon`). Two shapes, not one, because
+ * `Ref(someEntity)` (chant #1152) wraps the entity itself — a
+ * CloudFormation Parameter carries no attributes at all, so `Ref(param)`
+ * can never contain a nested AttrRef for a single-shape search to find. */
+type Anchor = { readonly kind: "attrRef"; readonly ref: AttrRef } | { readonly kind: "declarable"; readonly entity: Declarable };
+
+/** Find the first AttrRef or directly-referenced Declarable anywhere inside a
+ * value (walking intrinsics/objects/arrays), so a wrapping intrinsic can
+ * still borrow its source's lexicon. Duck-type, not `instanceof` (chant
+ * #1137): a lexicon built against a separate copy of `@intentius/chant`
+ * produces AttrRefs/Declarables that fail `instanceof` here but carry the
+ * same shape (`isDeclarable`'s `Symbol.for` marker is already dual-copy-safe
+ * on its own) — missing one would make the walk recurse into its own
+ * (unhelpful) fields instead of stopping on it, silently failing to find the
+ * anchor. */
+function findAnchor(value: unknown, seen = new Set<unknown>()): Anchor | undefined {
   if (value === null || typeof value !== "object" || seen.has(value)) return undefined;
-  if (isAttrRefLike(value)) return value;
+  if (isAttrRefLike(value)) return { kind: "attrRef", ref: value };
+  if (isDeclarable(value)) return { kind: "declarable", entity: value };
   seen.add(value);
   const children = Array.isArray(value) ? value : Object.values(value as Record<string, unknown>);
   for (const child of children) {
-    const found = firstAttrRef(child, seen);
+    const found = findAnchor(child, seen);
     if (found) return found;
   }
   return undefined;
 }
 
+/** Derive the lexicon an anchor belongs to: an AttrRef borrows its (deref'd)
+ * parent's `.lexicon`; a directly-referenced Declarable reports its own. */
+function anchorLexicon(anchor: Anchor | undefined): string {
+  if (!anchor) return "unknown";
+  if (anchor.kind === "declarable") return anchor.entity.lexicon;
+  const parent = anchor.ref.parent.deref();
+  return parent && typeof (parent as Record<string, unknown>).lexicon === "string"
+    ? ((parent as Record<string, unknown>).lexicon as string)
+    : "unknown";
+}
+
 /**
  * Type guard for StackOutput.
  */
@@ -106,16 +128,15 @@ export function stackOutput(
     );
   }
   // Derive lexicon from the referenced entity — for a bare AttrRef, its parent;
-  // for an intrinsic (Join etc.), the first AttrRef nested inside it. A
-  // foreign-copy AttrRef failing raw `instanceof` here would fall to
-  // `firstAttrRef`, which (before its own #1137 fix) would also miss it —
+  // for an intrinsic (Join etc.), the first AttrRef or directly-referenced
+  // Declarable nested inside it (chant #1152: `Ref(param)`/`Ref(resource)`
+  // wrap the entity itself, not one of its attributes). A foreign-copy
+  // AttrRef/Declarable failing raw `instanceof` here would fall to
+  // `findAnchor`, which (before its own #1137 fix) would also miss it —
   // silently anchoring on nothing and recording `lexicon: "unknown"`.
-  const anchor = typeof ref === "string" ? undefined : isAttrRefLike(ref) ? ref : firstAttrRef(ref);
-  const parent = anchor?.parent.deref();
-  const derived = parent && typeof (parent as Record<string, unknown>).lexicon === "string"
-    ? (parent as Record<string, unknown>).lexicon as string
-    : "unknown";
-  const lexicon = options?.lexicon ?? derived;
+  const anchor: Anchor | undefined =
+    typeof ref === "string" ? undefined : isAttrRefLike(ref) ? { kind: "attrRef", ref } : findAnchor(ref);
+  const lexicon = options?.lexicon ?? anchorLexicon(anchor);
 
   const output: StackOutput = {
     [STACK_OUTPUT_MARKER]: true,