@intentius/chant-lexicon-aws 0.44.9 → 0.44.12

package/src/api/sigv4.ts

@@ -0,0 +1,243 @@
+/**
+ * AWS Signature Version 4, for the shared read transport (#1686).
+ *
+ * Two modules asked for this by name before it existed: `./read-client.ts` and
+ * cedar's `lexicons/cedar/src/avp/client.ts` both send a placeholder
+ * `Signature=unsigned` `Authorization` header that carries a credential scope
+ * and nothing else, and both say in prose that the real thing belongs here
+ * once rather than twice. Nothing else in the repo signs an AWS request — the
+ * appliers (`op/activities/aws-apply.ts`) are unsigned too, which is why the
+ * native paths have been emulator-scoped.
+ *
+ * ## No dependency
+ *
+ * SigV4 is four HMACs and two SHA-256s. `node:crypto` has both, so signing
+ * costs nothing in the dependency tree — which matters here, because the whole
+ * reason these transports are hand-written is to keep `@aws-sdk/*` and its
+ * thirty-odd transitive packages out of a lexicon.
+ *
+ * ## What is signed, and what is not
+ *
+ * Header signing only. Query-string (presigned-URL) signing has no caller: the
+ * read paths POST to a service endpoint, they do not hand out URLs.
+ *
+ * `host` is signed but never emitted. `fetch` computes `Host` from the URL and
+ * forbids overriding it, so the signer derives the same value from the URL it
+ * was given. A transport that rewrites the URL underneath the signer — a proxy
+ * that keeps the original `Host`, say — would invalidate the signature; the
+ * injectable-HTTP seam is for tests and emulators, not for URL rewriting.
+ */
+import { createHash, createHmac } from "node:crypto";
+
+const ALGORITHM = "AWS4-HMAC-SHA256";
+const TERMINATOR = "aws4_request";
+
+/** SHA-256 of the empty string — the payload hash of every bodyless request. */
+export const EMPTY_PAYLOAD_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+
+/**
+ * Headers that must not be signed even when a caller sets them: `authorization`
+ * is the output, and the others are rewritten in transit by proxies and agents,
+ * so signing them produces intermittent 403s rather than security.
+ */
+const UNSIGNABLE = new Set(["authorization", "connection", "expect", "user-agent", "x-amzn-trace-id"]);
+
+/** A resolved credential set. `sessionToken` is present for STS/role credentials. */
+export interface AwsCredentials {
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+}
+
+/**
+ * The credential injection seam: a function the caller supplies to decide, by
+ * whatever means it likes, what to sign with. Returning `undefined` means "this
+ * process has no credentials" and is respected as an answer, not overridden.
+ */
+export type AwsCredentialResolver = () => AwsCredentials | undefined;
+
+/** Either literal credentials or a resolver for them. */
+export type AwsCredentialSource = AwsCredentials | AwsCredentialResolver;
+
+/**
+ * Credentials for a request: explicit → environment → absent.
+ *
+ * A resolver function is authoritative — if one is injected and it declines,
+ * the environment is not consulted behind its back, because the point of
+ * injecting one is to control the answer. Literal credentials are likewise
+ * final. Only the no-source case falls through to `AWS_ACCESS_KEY_ID` /
+ * `AWS_SECRET_ACCESS_KEY` (plus `AWS_SESSION_TOKEN` when set), and a half-set
+ * environment — a key id with no secret — is absent rather than a signature
+ * that cannot verify.
+ *
+ * Deliberately not implemented: the profile file, IMDS, and the container
+ * credential endpoints. Each is a separate transport with its own failure and
+ * caching story; a caller that has those can resolve them itself and pass the
+ * result in, which is what the resolver seam is for.
+ */
+export function resolveCredentials(
+  source?: AwsCredentialSource,
+  env: Record<string, string | undefined> = process.env,
+): AwsCredentials | undefined {
+  if (typeof source === "function") return source();
+  if (source) return source;
+  const accessKeyId = env.AWS_ACCESS_KEY_ID;
+  const secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
+  if (!accessKeyId || !secretAccessKey) return undefined;
+  return {
+    accessKeyId,
+    secretAccessKey,
+    ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}),
+  };
+}
+
+/** One request to sign. `headers` are the caller's; the signer adds its own. */
+export interface SigV4Request {
+  method: string;
+  /** Absolute URL. Its host is signed and its path/query are canonicalized. */
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+  /** Service name as it appears in the credential scope (`cloudformation`, `cloudcontrolapi`, …). */
+  service: string;
+  region: string;
+  credentials: AwsCredentials;
+  /** Signing clock. Injected by tests; otherwise now. */
+  now?: Date;
+}
+
+/** `YYYYMMDDTHHMMSSZ` — the `X-Amz-Date` format, which is ISO-8601 basic. */
+export function amzDate(date: Date): string {
+  return date.toISOString().replace(/[:-]|\.\d{3}/g, "");
+}
+
+/** Lowercase hex SHA-256. */
+export function sha256Hex(payload: string): string {
+  return createHash("sha256").update(payload, "utf8").digest("hex");
+}
+
+function hmac(key: Buffer | string, data: string): Buffer {
+  return createHmac("sha256", key).update(data, "utf8").digest();
+}
+
+/**
+ * The signing key: four chained HMACs from the secret, so the key on the wire
+ * is scoped to one day, one region and one service rather than being the
+ * account secret itself.
+ */
+export function signingKey(secretAccessKey: string, day: string, region: string, service: string): Buffer {
+  const dateKey = hmac(`AWS4${secretAccessKey}`, day);
+  const regionKey = hmac(dateKey, region);
+  const serviceKey = hmac(regionKey, service);
+  return hmac(serviceKey, TERMINATOR);
+}
+
+/**
+ * RFC 3986 percent-encoding. `encodeURIComponent` leaves `!'()*` alone and AWS
+ * does not, which is the difference between a signature that verifies and one
+ * that does not for any path or parameter containing them.
+ */
+function encodeRfc3986(value: string): string {
+  return encodeURIComponent(value).replace(
+    /[!'()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+/**
+ * The canonical path.
+ *
+ * Every caller of this module POSTs to `/`, so the one place implementations
+ * genuinely diverge — S3 signs the path once-encoded, every other service signs
+ * it twice-encoded — never arises. Segments are encoded once; a future caller
+ * with a real path on a non-S3 service is the moment to revisit that.
+ */
+function canonicalPath(pathname: string): string {
+  if (!pathname || pathname === "/") return "/";
+  return pathname.split("/").map(encodeRfc3986).join("/");
+}
+
+/** Query parameters sorted by name, then by value, each side encoded. */
+function canonicalQuery(search: URLSearchParams): string {
+  const pairs: Array<[string, string]> = [];
+  search.forEach((value, name) => pairs.push([encodeRfc3986(name), encodeRfc3986(value)]));
+  pairs.sort((a, b) => (a[0] === b[0] ? (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0) : a[0] < b[0] ? -1 : 1));
+  return pairs.map(([name, value]) => `${name}=${value}`).join("&");
+}
+
+/**
+ * Header names lowercased, values trimmed with internal whitespace runs
+ * collapsed, sorted by name. Returns the canonical block and the `;`-joined
+ * signed-header list that has to agree with it exactly.
+ */
+export function canonicalHeaders(headers: Record<string, string>): { canonical: string; signed: string } {
+  const entries = Object.entries(headers)
+    .map(([name, value]) => [name.toLowerCase().trim(), value.trim().replace(/\s+/g, " ")] as const)
+    .filter(([name]) => !UNSIGNABLE.has(name))
+    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  return {
+    canonical: entries.map(([name, value]) => `${name}:${value}\n`).join(""),
+    signed: entries.map(([name]) => name).join(";"),
+  };
+}
+
+/** The canonical request, verbatim as it is hashed into the string to sign. */
+export function canonicalRequest(
+  method: string,
+  url: URL,
+  headers: Record<string, string>,
+  payloadHash: string,
+): { canonical: string; signed: string } {
+  const { canonical: headerBlock, signed } = canonicalHeaders(headers);
+  return {
+    canonical: [
+      method.toUpperCase(),
+      canonicalPath(url.pathname),
+      canonicalQuery(url.searchParams),
+      headerBlock,
+      signed,
+      payloadHash,
+    ].join("\n"),
+    signed,
+  };
+}
+
+/** The string to sign: algorithm, timestamp, scope, hashed canonical request. */
+export function stringToSign(timestamp: string, scope: string, canonical: string): string {
+  return [ALGORITHM, timestamp, scope, sha256Hex(canonical)].join("\n");
+}
+
+/**
+ * The caller's headers plus everything SigV4 adds: `x-amz-date`,
+ * `x-amz-content-sha256`, `x-amz-security-token` when the credentials are
+ * temporary, and the `Authorization` header itself.
+ *
+ * `host` is signed (AWS requires it) but not returned — see the module header.
+ */
+export function signRequest(request: SigV4Request): Record<string, string> {
+  const url = new URL(request.url);
+  const timestamp = amzDate(request.now ?? new Date());
+  const day = timestamp.slice(0, 8);
+  const payloadHash = request.body.length === 0 ? EMPTY_PAYLOAD_SHA256 : sha256Hex(request.body);
+
+  const signable: Record<string, string> = {
+    ...request.headers,
+    host: url.host,
+    "x-amz-date": timestamp,
+    "x-amz-content-sha256": payloadHash,
+    ...(request.credentials.sessionToken ? { "x-amz-security-token": request.credentials.sessionToken } : {}),
+  };
+
+  const { canonical, signed } = canonicalRequest(request.method, url, signable, payloadHash);
+  const scope = `${day}/${request.region}/${request.service}/${TERMINATOR}`;
+  const key = signingKey(request.credentials.secretAccessKey, day, request.region, request.service);
+  const signature = hmac(key, stringToSign(timestamp, scope, canonical)).toString("hex");
+
+  const { host: _host, ...emitted } = signable;
+  return {
+    ...emitted,
+    authorization:
+      `${ALGORITHM} Credential=${request.credentials.accessKeyId}/${scope}, ` +
+      `SignedHeaders=${signed}, Signature=${signature}`,
+  };
+}

package/src/identity-observe.test.ts

@@ -0,0 +1,146 @@
+/**
+ * The identity fallback (#1647) — unit half. The carve state in miniature: a
+ * declared Bucket absent from every stack, present live, named precisely by
+ * its own `BucketName`. The Cloud Control edge is the injected `http` seam
+ * `read-client` already exposes.
+ */
+import { describe, test, expect } from "vitest";
+import { declaredIdentifier, observeByIdentity } from "./identity-observe";
+
+const entity = (entityType: string, props: Record<string, unknown>) => ({ entityType, props });
+
+describe("declaredIdentifier (#1647)", () => {
+  test("a scalar primary identifier reads straight off the props", () => {
+    expect(declaredIdentifier("AWS::S3::Bucket", { BucketName: "acme-platform-assets-prod" })).toBe(
+      "acme-platform-assets-prod",
+    );
+  });
+
+  test("absent, empty, or non-scalar identifier parts refuse — a Ref is not an identity", () => {
+    expect(declaredIdentifier("AWS::S3::Bucket", {})).toBeUndefined();
+    expect(declaredIdentifier("AWS::S3::Bucket", { BucketName: "" })).toBeUndefined();
+    expect(declaredIdentifier("AWS::S3::Bucket", { BucketName: { Ref: "Other" } })).toBeUndefined();
+  });
+
+  test("an unknown type has no identifier to spell", () => {
+    expect(declaredIdentifier("AWS::Made::Up", { Name: "x" })).toBeUndefined();
+  });
+});
+
+/** A Cloud Control `GetResource` answer, double-encoded the way the API is. */
+const ccFound = (identifier: string, properties: Record<string, unknown>) => ({
+  status: 200,
+  text: JSON.stringify({
+    ResourceDescription: { Identifier: identifier, Properties: JSON.stringify(properties) },
+  }),
+});
+
+const ccError = (type: string, message: string) => ({
+  status: 400,
+  text: JSON.stringify({ __type: type, message }),
+});
+
+describe("observeByIdentity (#1647)", () => {
+  const bucket = new Map([["assets", entity("AWS::S3::Bucket", { BucketName: "acme-platform-assets-prod" })]]);
+
+  test("a live identifier-named resource reads OBSERVED — external, foreign, never absent", async () => {
+    const calls: Array<{ url: string; body: string }> = [];
+    const { resources, queried } = await observeByIdentity(["assets"], bucket, {}, {
+      http: async (url, init) => {
+        calls.push({ url, body: init.body });
+        return ccFound("acme-platform-assets-prod", { BucketName: "acme-platform-assets-prod", SecretToken: "s3cr3t" });
+      },
+    });
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toContain("cloudcontrol");
+    expect(resources.assets).toMatchObject({
+      type: "AWS::S3::Bucket",
+      physicalId: "acme-platform-assets-prod",
+      status: "EXTERNAL",
+      ownership: "foreign",
+    });
+    // Live properties ride along, sensitive keys scrubbed like stack outputs.
+    expect(resources.assets.attributes).toMatchObject({ BucketName: "acme-platform-assets-prod", SecretToken: "[REDACTED]" });
+    // #1620: the attempted address is on the wire whatever the verdict.
+    expect(queried.assets).toContain("AWS::S3::Bucket");
+    expect(queried.assets).toContain("acme-platform-assets-prod");
+  });
+
+  test("a genuine miss keeps the stack's absent verdict, with the address still recorded", async () => {
+    const { resources, queried } = await observeByIdentity(["assets"], bucket, {}, {
+      http: async () => ccError("ResourceNotFoundException", "no such bucket"),
+    });
+    expect(resources.assets).toBeUndefined();
+    expect(queried.assets).toBeDefined();
+  });
+
+  test("an emulator without Cloud Control at all keeps the absent verdict — never a hole, or pre-first-apply plans stop proposing create", async () => {
+    const { resources } = await observeByIdentity(["assets"], bucket, {}, {
+      http: async () => ccError("UnsupportedOperation", "not supported"),
+    });
+    expect(resources.assets).toBeUndefined();
+  });
+
+  // Floci serves ListResources but answers UnsupportedOperation for
+  // GetResource (read-client's own note) — and the emulator is where the carve
+  // walkthrough films the observe beat. Verified against Floci 1.5.34 on the
+  // behold demo: the list leg is what turns the miss into a read.
+  test("GetResource-unsupported falls back to ListResources and matches the identifier (Floci)", async () => {
+    const targets: string[] = [];
+    const { resources } = await observeByIdentity(["assets"], bucket, {}, {
+      http: async (_url, init) => {
+        const target = (init.headers as Record<string, string>)["x-amz-target"] ?? "";
+        targets.push(target);
+        if (target.endsWith("GetResource")) return ccError("UnsupportedOperation", "Operation GetResource is not supported.");
+        return {
+          status: 200,
+          text: JSON.stringify({
+            ResourceDescriptions: [
+              { Identifier: "some-other-bucket", Properties: JSON.stringify({ BucketName: "some-other-bucket" }) },
+              { Identifier: "acme-platform-assets-prod", Properties: JSON.stringify({ BucketName: "acme-platform-assets-prod" }) },
+            ],
+          }),
+        };
+      },
+    });
+    expect(targets.some((t) => t.endsWith("ListResources"))).toBe(true);
+    expect(resources.assets).toMatchObject({
+      type: "AWS::S3::Bucket",
+      physicalId: "acme-platform-assets-prod",
+      status: "EXTERNAL",
+      ownership: "foreign",
+    });
+  });
+
+  test("the list leg missing the identifier keeps the absent verdict", async () => {
+    const { resources } = await observeByIdentity(["assets"], bucket, {}, {
+      http: async (_url, init) => {
+        const target = (init.headers as Record<string, string>)["x-amz-target"] ?? "";
+        if (target.endsWith("GetResource")) return ccError("UnsupportedOperation", "not supported");
+        return { status: 200, text: JSON.stringify({ ResourceDescriptions: [] }) };
+      },
+    });
+    expect(resources.assets).toBeUndefined();
+  });
+
+  test("entities the stack already answered for are never re-read", async () => {
+    let called = 0;
+    const already = { assets: { type: "AWS::S3::Bucket", physicalId: "b", status: "CREATE_COMPLETE" } };
+    const { resources } = await observeByIdentity(["assets"], bucket, already, {
+      http: async () => ((called += 1), ccFound("x", {})),
+    });
+    expect(called).toBe(0);
+    expect(resources).toEqual({});
+  });
+
+  test("entities with no spellable identifier are skipped without a call", async () => {
+    let called = 0;
+    const anonymous = new Map([["q", entity("AWS::SQS::Queue", {})]]);
+    const { resources, queried } = await observeByIdentity(["q"], anonymous, {}, {
+      http: async () => ((called += 1), ccFound("x", {})),
+    });
+    expect(called).toBe(0);
+    expect(resources).toEqual({});
+    expect(queried).toEqual({});
+  });
+});

package/src/identity-observe.ts

@@ -0,0 +1,137 @@
+/**
+ * The identity fallback on the stack read (#1647).
+ *
+ * `describeResources` asks CloudFormation exactly one question — is there a
+ * logical id named <entity> in this stack? — which reads a freshly
+ * carve-emitted, still-Terraform-owned resource as confirmed-absent even
+ * though the declared `BucketName` names it precisely. When a declared entity
+ * is absent from the stack AND its props spell the type's full primary
+ * identifier (the spec knowledge the codegen already compiled into
+ * `lexicon-aws.json`), ask Cloud Control for it by identity. Found means
+ * OBSERVED: `ownership: "foreign"` (it exists and something other than this
+ * stack owns it — Terraform, a console hand, another tool) and
+ * `status: "EXTERNAL"` (live outside the stack, deliberately not a
+ * CloudFormation status word).
+ *
+ * Best-effort ON TOP of a stack answer, never instead of one: a genuine miss
+ * (`ResourceNotFoundException`) keeps the stack's absent verdict, and so does
+ * every other refusal (`UnsupportedOperation` — a Floci without Cloud
+ * Control — credentials, throttling). The stack read succeeded; absence at
+ * stack scope is an honest verdict this fallback can refine but must never
+ * degrade into a hole, or a pre-first-apply plan would stop proposing
+ * `create` the moment the emulator lacks Cloud Control.
+ */
+import { createRequire } from "module";
+import { AwsReadError, getResource, listResources, type AwsReadClientOptions, type CloudControlDescription } from "./api/read-client";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+
+const require = createRequire(import.meta.url);
+
+interface LexiconEntry {
+  resourceType: string;
+  kind: string;
+  primaryIdentifier?: string[];
+}
+
+let byResourceType: Map<string, LexiconEntry> | undefined;
+function manifestByType(): Map<string, LexiconEntry> {
+  if (!byResourceType) {
+    const manifest = require("./generated/lexicon-aws.json") as Record<string, LexiconEntry>;
+    byResourceType = new Map(Object.values(manifest).map((e) => [e.resourceType, e]));
+  }
+  return byResourceType;
+}
+
+/**
+ * The Cloud Control identifier the declared props spell, or undefined when the
+ * type has no primary identifier on record or any part of it is absent or
+ * non-scalar (a Ref, an intrinsic, a server-assigned name). Multi-part
+ * identifiers join with `|`, Cloud Control's own separator.
+ */
+export function declaredIdentifier(entityType: string, props: Record<string, unknown>): string | undefined {
+  const entry = manifestByType().get(entityType);
+  const parts = entry?.primaryIdentifier;
+  if (!entry || entry.kind !== "resource" || !parts || parts.length === 0) return undefined;
+  const values: string[] = [];
+  for (const part of parts) {
+    const v = props[part];
+    if (typeof v !== "string" && typeof v !== "number") return undefined;
+    const s = String(v);
+    if (!s) return undefined;
+    values.push(s);
+  }
+  return values.join("|");
+}
+
+/**
+ * `GetResource`, with a `ListResources` + identifier-match fallback when the
+ * endpoint says the operation itself is unsupported. That is Floci's exact
+ * answer (read-client's own note) while it serves `ListResources` fine — and
+ * an emulator is exactly where the carve state lives, so without this leg the
+ * fallback proves itself everywhere except the one place the walkthrough
+ * films it. Every other refusal propagates: the caller decides what a failed
+ * refinement means.
+ */
+async function readByIdentity(
+  typeName: string,
+  identifier: string,
+  client: AwsReadClientOptions,
+): Promise<CloudControlDescription | null> {
+  try {
+    return await getResource(typeName, identifier, client);
+  } catch (err) {
+    if (!(err instanceof AwsReadError) || err.code !== "UnsupportedOperation") throw err;
+    const listed = await listResources(typeName, client);
+    return listed.find((d) => d.identifier === identifier) ?? null;
+  }
+}
+
+/** The same scrub the stack-output path applies, on live property KEYS. */
+function redactSensitive(properties: Record<string, unknown>): Record<string, unknown> | undefined {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(properties)) {
+    out[key] = /password|secret|token/i.test(key) ? "[REDACTED]" : value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Identity-read every entity the stack did not answer for and whose props
+ * spell an identifier. `already` is the stack's answer — an entity the stack
+ * DID return is never re-read. The `queried` map records the address each
+ * attempted read was issued against (#1620), whatever the verdict.
+ */
+export async function observeByIdentity(
+  entityNames: string[],
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }> | undefined,
+  already: Record<string, ResourceMetadata>,
+  client: AwsReadClientOptions,
+): Promise<{ resources: Record<string, ResourceMetadata>; queried: Record<string, string> }> {
+  const resources: Record<string, ResourceMetadata> = {};
+  const queried: Record<string, string> = {};
+  if (!entities) return { resources, queried };
+  for (const name of entityNames) {
+    if (already[name]) continue;
+    const entity = entities.get(name);
+    if (!entity) continue;
+    const identifier = declaredIdentifier(entity.entityType, entity.props ?? {});
+    if (!identifier) continue;
+    queried[name] = `cloudcontrol:GetResource:${entity.entityType}:${identifier}`;
+    try {
+      const found = await readByIdentity(entity.entityType, identifier, client);
+      if (!found) continue;
+      resources[name] = {
+        type: entity.entityType,
+        physicalId: found.identifier || identifier,
+        status: "EXTERNAL",
+        ownership: "foreign",
+        ...(redactSensitive(found.properties) ? { attributes: redactSensitive(found.properties) } : {}),
+      };
+    } catch {
+      // Refusals of every kind keep the stack's verdict — see the module
+      // comment for why a failed refinement must not become a hole.
+      continue;
+    }
+  }
+  return { resources, queried };
+}

package/src/index.ts

@@ -52,8 +52,21 @@ export {
   type AwsReadClientOptions,
   type CloudControlDescription,
   type StackResource,
+  type AwsCredentials,
+  type AwsCredentialResolver,
+  type AwsCredentialSource,
 } from "./api/read-client";
 
+// SigV4 (#1686). Exported as its own surface because it is deliberately not
+// specific to this transport: cedar's AVP client is the next caller, and the
+// point of the module is that there is one signer rather than one per lexicon.
+export {
+  signRequest,
+  resolveCredentials,
+  EMPTY_PAYLOAD_SHA256,
+  type SigV4Request,
+} from "./api/sigv4";
+
 // Intrinsics
 export {
   Sub,

package/src/lifecycle-integration.test.ts

@@ -143,6 +143,75 @@ describe("aws lifecycle integration (#163)", () => {
     expect(cs2.entries.find((e) => e.name === "MyBucket")!.action).toBe("noop");
   });
 
+  // #1647 — the carve state, end to end: terraform applied the bucket, carve
+  // emitted a carveout declaring it by BucketName, and no CFN stack has ever
+  // heard of it. The stack read alone said confirmed-absent (missing → a plan
+  // proposing create for a bucket that EXISTS); the identity fallback asks
+  // Cloud Control by the declared identifier and the verdict comes back
+  // observed.
+  test("identity fallback: a declared, stack-absent, live resource reads observed, not missing (#1647)", async () => {
+    const routeBoth = (cc: { status?: number; text: string }): void => {
+      vi.spyOn(globalThis, "fetch").mockImplementation((async (url: string, init: { body: string; headers?: Record<string, string> }) => {
+        const target = init.headers?.["x-amz-target"] ?? "";
+        if (target.endsWith("GetResource")) return { status: cc.status ?? 200, text: () => Promise.resolve(cc.text) };
+        const action = new URLSearchParams(init.body).get("Action") ?? "";
+        return {
+          status: 200,
+          text: () => Promise.resolve(action === "DescribeStackResources" ? stackResourcesXml([]) : stackOutputsXml()),
+        };
+      }) as unknown as typeof fetch);
+    };
+
+    const entities = new Map([
+      ["assets", { entityType: "AWS::S3::Bucket", props: { BucketName: "acme-platform-assets-prod" } }],
+    ]);
+
+    routeBoth({
+      text: JSON.stringify({
+        ResourceDescription: {
+          Identifier: "acme-platform-assets-prod",
+          Properties: JSON.stringify({ BucketName: "acme-platform-assets-prod" }),
+        },
+      }),
+    });
+    const observed = normalizeObservation(
+      await awsPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["assets"],
+        entities,
+      }),
+    );
+    expect(observed.resources.assets).toMatchObject({
+      type: "AWS::S3::Bucket",
+      status: "EXTERNAL",
+      ownership: "foreign",
+    });
+    // #1620: the identity read's address rides the observation.
+    expect(observed.queried.assets).toContain("acme-platform-assets-prod");
+
+    // Through the change set: declared + live → noop, never create. `foreign`
+    // ownership never escalates anything (#120's rule holds).
+    const cs = buildChangeSet("prod", { declared: new Set(["assets"]), observedNow: observed.resources, observedThen: undefined });
+    expect(cs.entries.find((e) => e.name === "assets")!.action).toBe("noop");
+
+    // An emulator without Cloud Control keeps today's verdict exactly: absent,
+    // create proposed — the fallback must not turn pre-first-apply into a hole.
+    routeBoth({ status: 400, text: JSON.stringify({ __type: "UnsupportedOperation", message: "not supported" }) });
+    const degraded = normalizeObservation(
+      await awsPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["assets"],
+        entities,
+      }),
+    );
+    expect(degraded.resources.assets).toBeUndefined();
+    expect(degraded.unobserved.assets).toBeUndefined();
+    const cs2 = buildChangeSet("prod", { declared: new Set(["assets"]), observedNow: degraded.resources, observedThen: undefined });
+    expect(cs2.entries.find((e) => e.name === "assets")!.action).toBe("create");
+  });
+
   describe("describeStackStatus (#57 — per-component stack presence)", () => {
     const err = (stderr: string) => ({ stdout: "", stderr, exitCode: 255 });
 

package/src/op/activities/index.ts

@@ -4,6 +4,14 @@
  * emulator lifecycle (`flociUp`/`flociDown`) and the native CloudFormation
  * applier (`awsApply`), which calls the CloudFormation API directly rather than
  * shelling `aws` — the direct twin of `azApply`/`gcpApply`.
+ *
+ * The registry keys every exported *function* here by its name, so only the
+ * activities themselves belong in this barrel. `awsAgentCoreFetchTrace`'s
+ * helpers — the normalizer, the JSON coercion, the `ListEvents` walk — stay
+ * importable from `@intentius/chant-lexicon-aws/agentcore/trace-fetch` rather
+ * than being registered as activities nobody would ever name in a step, and the
+ * pure renderer lives one module further out again, in
+ * `@intentius/chant-lexicon-aws/agentcore/trace-render`.
  */
 export {
   flociUp,
@@ -35,3 +43,10 @@ export {
   isTerminalStatus,
 } from "./aws-apply";
 export type { AwsApplyArgs, AwsHttp } from "./aws-apply";
+
+export { awsAgentCoreFetchTrace } from "../../agentcore/trace-fetch";
+export type {
+  AgentCoreTraceSource,
+  AwsAgentCoreFetchTraceArgs,
+  AwsAgentCoreFetchTraceResult,
+} from "../../agentcore/trace-fetch";