@intentius/chant-lexicon-aws 0.46.0 → 0.50.0

package/src/composites/monitoring-stack.ts

@@ -0,0 +1,164 @@
+/**
+ * MonitoringStack — a CloudWatch dashboard wired to up to three named
+ * metrics, with an optional alarm per metric.
+ *
+ * The recurring hand-rolled shape the aws-bench corpus surfaced: a team
+ * stands up a `cloudwatch.Dashboard`, a `cloudwatch.Metric` per resource it
+ * cares about, and a near-identical `cloudwatch.Alarm` next to each one — 44
+ * combined dashboard+alarm+metric instantiations across the corpus' 8 real
+ * CDK apps, nothing equivalent shipped in chant (epic #1139).
+ *
+ * Fixed `metric1..metric3` slots, not a `metrics: MetricSpec[]` array — a
+ * loop building `Alarm` resources from an array is exactly the control-flow-
+ * over-resources shape EVL002/EVL003 rule out for reference composites (see
+ * `EksCluster`'s `addon1..addon3`, this directory). A fourth metric is a bare
+ * `Alarm` + a hand-edited `CwDashboard.DashboardBody` the estate declares
+ * directly.
+ *
+ * What is deliberately NOT here:
+ *  - Notification wiring. `alarm.alarmActions` on each metric takes ARNs the
+ *    caller already has (an SNS topic from `LambdaSns`, or hand-declared);
+ *    this composite does not create a `Topic`/`Subscription` itself — who
+ *    gets paged and on what channel is a real per-estate decision, not a
+ *    default worth guessing. `defaults.alarm1..3` is the escape hatch for
+ *    anything else on the alarm (e.g. `OKActions`, `DatapointsToAlarm`).
+ *  - Math-expression / composite / anomaly-detection alarms (`Alarm.Metrics`,
+ *    `AlarmModel`) — single-metric threshold alarms only.
+ *  - Dynamic (`Ref`/`GetAtt`/`Sub`) values inside the dashboard body.
+ *    `CwDashboard.DashboardBody` is one flat JSON string CloudFormation does
+ *    not template, so each metric's `namespace`/`metricName`/`dimension.value`
+ *    must be a literal the caller already knows — the physical name they set
+ *    on the monitored resource, not one CloudFormation generates. The `Alarm`
+ *    resources carry no such limit: `Dimensions` is a real structured
+ *    property, so `alarm.dimensionValue` accepts `Value<string>` and can
+ *    reference a sibling resource by `Ref`/`GetAtt`.
+ */
+import { Composite, mergeDefaults, type Value } from "@intentius/chant";
+import { Alarm, CwDashboard } from "../generated";
+
+export interface MonitoringMetricSpec {
+  /** Dashboard widget title, and the alarm's default `AlarmName`. */
+  title: string;
+  /** CloudWatch namespace, e.g. `"AWS/Lambda"`, `"AWS/DynamoDB"`. */
+  namespace: string;
+  /** Metric name within the namespace, e.g. `"Errors"`, `"ConsumedReadCapacityUnits"`. */
+  metricName: string;
+  /**
+   * Dimension identifying which resource emits the metric, e.g.
+   * `{ name: "FunctionName", value: "my-fn" }`. Omit for an account/region-
+   * wide metric. `value` must be a literal — see the dashboard-body note above.
+   */
+  dimension?: { name: string; value: string };
+  /** Statistic for both the widget and (if alarmed) the alarm. Default `"Sum"`. */
+  statistic?: string;
+  /** Period in seconds, for both the widget and the alarm. Default `300`. */
+  period?: number;
+  /** Alarm this metric when set; omit for a dashboard-only metric. */
+  alarm?: {
+    threshold: number;
+    /** Default `"GreaterThanThreshold"`. */
+    comparisonOperator?: string;
+    /** Default `1`. */
+    evaluationPeriods?: number;
+    treatMissingData?: "breaching" | "ignore" | "missing" | "notBreaching";
+    /** ARNs to notify on ALARM — an existing SNS topic, typically. */
+    alarmActions?: Value<string>[];
+    /**
+     * Dimension value for the alarm. Defaults to `dimension.value`; set this
+     * instead when the alarm needs to track a `Ref`/`GetAtt` the dashboard
+     * widget cannot (see the dashboard-body note above).
+     */
+    dimensionValue?: Value<string>;
+  };
+}
+
+export interface MonitoringStackProps {
+  /** `Value<string>`: a name is routinely built with `Sub`/`Ref` (#1366). */
+  dashboardName?: Value<string>;
+  metric1: MonitoringMetricSpec;
+  metric2?: MonitoringMetricSpec;
+  metric3?: MonitoringMetricSpec;
+  tags?: Array<{ Key: string; Value: string }>;
+  defaults?: {
+    dashboard?: Partial<ConstructorParameters<typeof CwDashboard>[0]>;
+    alarm1?: Partial<ConstructorParameters<typeof Alarm>[0]>;
+    alarm2?: Partial<ConstructorParameters<typeof Alarm>[0]>;
+    alarm3?: Partial<ConstructorParameters<typeof Alarm>[0]>;
+  };
+}
+
+/** A CloudWatch dashboard "metric" widget, stacked full-width below the last. */
+function widget(spec: MonitoringMetricSpec, index: number) {
+  // Two literal-array branches, not a spread — EVL004 only traces a spread
+  // source to a *module-level* const (packages/core/src/lint/rules/
+  // evl004-spread-non-const.ts's isConstIdentifier walks sourceFile.statements
+  // only), so a same-function `const dims = [...]` here reads as non-const
+  // even though it is one. A ternary between two literals sidesteps the gap
+  // instead of fighting it.
+  const metricTuple = spec.dimension
+    ? [spec.namespace, spec.metricName, spec.dimension.name, spec.dimension.value]
+    : [spec.namespace, spec.metricName];
+  return {
+    type: "metric",
+    x: 0,
+    y: index * 6,
+    width: 24,
+    height: 6,
+    properties: {
+      title: spec.title,
+      metrics: [metricTuple],
+      period: spec.period ?? 300,
+      stat: spec.statistic ?? "Sum",
+      view: "timeSeries",
+    },
+  };
+}
+
+function alarmProps(spec: MonitoringMetricSpec) {
+  const a = spec.alarm!;
+  return {
+    AlarmName: spec.title,
+    AlarmDescription: `${spec.title} breached its threshold`,
+    Namespace: spec.namespace,
+    MetricName: spec.metricName,
+    Dimensions: spec.dimension
+      ? [{ Name: spec.dimension.name, Value: a.dimensionValue ?? spec.dimension.value }]
+      : undefined,
+    Statistic: spec.statistic ?? "Sum",
+    Period: spec.period ?? 300,
+    Threshold: a.threshold,
+    ComparisonOperator: a.comparisonOperator ?? "GreaterThanThreshold",
+    EvaluationPeriods: a.evaluationPeriods ?? 1,
+    TreatMissingData: a.treatMissingData,
+    AlarmActions: a.alarmActions,
+  };
+}
+
+export const MonitoringStack = Composite((props: MonitoringStackProps) => {
+  const { defaults } = props;
+  const specs = [props.metric1, props.metric2, props.metric3].filter(
+    (s): s is MonitoringMetricSpec => s !== undefined,
+  );
+
+  const dashboard = new CwDashboard(mergeDefaults({
+    DashboardName: props.dashboardName,
+    DashboardBody: JSON.stringify({ widgets: specs.map(widget) }),
+  }, defaults?.dashboard));
+
+  const alarm1 = props.metric1.alarm
+    ? new Alarm(mergeDefaults(alarmProps(props.metric1), defaults?.alarm1))
+    : undefined;
+  const alarm2 = props.metric2?.alarm
+    ? new Alarm(mergeDefaults(alarmProps(props.metric2), defaults?.alarm2))
+    : undefined;
+  const alarm3 = props.metric3?.alarm
+    ? new Alarm(mergeDefaults(alarmProps(props.metric3), defaults?.alarm3))
+    : undefined;
+
+  return {
+    dashboard,
+    ...(alarm1 ? { alarm1 } : {}),
+    ...(alarm2 ? { alarm2 } : {}),
+    ...(alarm3 ? { alarm3 } : {}),
+  };
+}, "MonitoringStack");

package/src/composites/nlb-service.ts

@@ -0,0 +1,117 @@
+import { Composite, mergeDefaults } from "@intentius/chant";
+import {
+  LoadBalancer,
+  TargetGroup,
+  TargetGroup_TargetDescription,
+  Listener,
+  Listener_Action,
+  Listener_Certificate,
+} from "../generated";
+
+export interface NlbServiceProps {
+  vpcId: string;
+  subnetIds: string[];
+  listenerPort?: number;
+  /** Port the target group forwards traffic to. Defaults to `listenerPort`. */
+  targetPort?: number;
+  /**
+   * Listener + target group protocol. `TLS` terminates TLS at the NLB and
+   * requires `certificateArn`; the other protocols pass traffic through
+   * unmodified, which is the common case for a Network Load Balancer.
+   */
+  protocol?: "TCP" | "UDP" | "TLS" | "TCP_UDP";
+  scheme?: "internet-facing" | "internal";
+  /**
+   * Target group target type. `ip` (the default) covers Fargate awsvpc tasks
+   * and any routable IP; use `instance` to register EC2 instance IDs directly,
+   * or `alb` to chain an NLB in front of an existing Application Load Balancer.
+   */
+  targetType?: "instance" | "ip" | "alb";
+  /**
+   * Static targets to register at creation time (instance IDs, IPs, or an ALB
+   * ARN depending on `targetType`). Omit when targets self-register instead —
+   * an ECS service, for instance, that references `targetGroup.TargetGroupArn`.
+   */
+  targets?: Array<{ id: string; port?: number; availabilityZone?: string }>;
+  /** ACM certificate ARN. Required when `protocol` is `TLS`. */
+  certificateArn?: string;
+  healthCheckProtocol?: "TCP" | "HTTP" | "HTTPS";
+  healthCheckPort?: string;
+  /** Only meaningful when `healthCheckProtocol` is `HTTP` or `HTTPS`. */
+  healthCheckPath?: string;
+  defaults?: {
+    nlb?: Partial<ConstructorParameters<typeof LoadBalancer>[0]>;
+    targetGroup?: Partial<ConstructorParameters<typeof TargetGroup>[0]>;
+    listener?: Partial<ConstructorParameters<typeof Listener>[0]>;
+  };
+}
+
+export const NlbService = Composite((props: NlbServiceProps) => {
+  if (props.protocol === "TLS" && !props.certificateArn) {
+    throw new Error("NlbService requires certificateArn when protocol is TLS");
+  }
+
+  const listenerPort = props.listenerPort ?? 80;
+  const targetPort = props.targetPort ?? listenerPort;
+  const protocol = props.protocol ?? "TCP";
+  const scheme = props.scheme ?? "internet-facing";
+  const targetType = props.targetType ?? "ip";
+  const { defaults: defs } = props;
+
+  // Network Load Balancer. Unlike the ALB composites, no security group is
+  // created here — NLBs pass through the client's source IP by default, so
+  // access control belongs on the target side (or via an explicit SG passed
+  // through `defaults.nlb`), not on the load balancer itself.
+  const nlb = new LoadBalancer(mergeDefaults({
+    Type: "network",
+    Scheme: scheme,
+    Subnets: props.subnetIds,
+  }, defs?.nlb));
+
+  // Target group. Static targets are optional — a `.map` keeps the `new`s
+  // out of a conditional (EVL002).
+  const targets = props.targets?.map((t) =>
+    new TargetGroup_TargetDescription({
+      Id: t.id,
+      Port: t.port,
+      AvailabilityZone: t.availabilityZone,
+    }),
+  );
+
+  const targetGroup = new TargetGroup(mergeDefaults({
+    TargetType: targetType,
+    Protocol: protocol,
+    Port: targetPort,
+    VpcId: props.vpcId,
+    HealthCheckProtocol: props.healthCheckProtocol ?? "TCP",
+    HealthCheckPort: props.healthCheckPort,
+    HealthCheckPath: props.healthCheckPath,
+    Targets: targets,
+  }, defs?.targetGroup));
+
+  // Listener — forwards to the target group. TLS carries the cert; a
+  // ternary keeps the `new` out of the `if` (EVL002).
+  const forwardAction = new Listener_Action({
+    Type: "forward",
+    TargetGroupArn: targetGroup.TargetGroupArn,
+  });
+
+  const listenerProps: Record<string, unknown> = {
+    LoadBalancerArn: nlb.LoadBalancerArn,
+    Port: listenerPort,
+    Protocol: protocol,
+    DefaultActions: [forwardAction],
+    Certificates:
+      protocol === "TLS" && props.certificateArn
+        ? [new Listener_Certificate({ CertificateArn: props.certificateArn })]
+        : undefined,
+  };
+
+  const listener = new Listener(mergeDefaults(listenerProps, defs?.listener));
+
+  return {
+    nlb,
+    targetGroup,
+    listener,
+  };
+}, "NlbService");

package/src/composites/step-functions-workflow.ts

@@ -0,0 +1,127 @@
+import { Composite, mergeDefaults, type Value } from "@intentius/chant";
+import {
+  Role,
+  Role_Policy,
+  LogGroup,
+  StateMachine,
+  StateMachine_LoggingConfiguration,
+  StateMachine_LogDestination,
+  StateMachine_CloudWatchLogsLogGroup,
+} from "../generated";
+import { LambdaActions } from "../actions/lambda";
+
+const stepFunctionsTrustPolicy = {
+  Version: "2012-10-17" as const,
+  Statement: [
+    {
+      Effect: "Allow" as const,
+      Principal: { Service: "states.amazonaws.com" },
+      Action: "sts:AssumeRole",
+    },
+  ],
+};
+
+/**
+ * CloudWatch Logs delivery actions a state machine's role needs to write to a
+ * log group via `LoggingConfiguration`. These act on the account's log
+ * delivery configuration rather than a specific ARN, so AWS documents them
+ * granted with `Resource: "*"` — see
+ * https://docs.aws.amazon.com/step-functions/latest/dg/cw-logs.html#cloudwatch-iam-policy
+ */
+const LOG_DELIVERY_ACTIONS = [
+  "logs:CreateLogDelivery",
+  "logs:GetLogDelivery",
+  "logs:UpdateLogDelivery",
+  "logs:DeleteLogDelivery",
+  "logs:ListLogDeliveries",
+  "logs:PutResourcePolicy",
+  "logs:DescribeResourcePolicies",
+  "logs:DescribeLogGroups",
+];
+
+const logDeliveryPolicyDocument = {
+  Version: "2012-10-17" as const,
+  // Log-delivery actions operate on the account's delivery configuration
+  // rather than a specific ARN — AWS documents them with Resource: "*".
+  Statement: [{ Effect: "Allow" as const, Action: LOG_DELIVERY_ACTIONS, Resource: "*" }],
+};
+
+export interface StepFunctionsWorkflowProps {
+  /** `Value<string>`: a name is routinely built with `Sub`/`Ref` (#1366). */
+  name?: Value<string>;
+  /**
+   * ASL state machine definition, authored as a plain object. Passed to
+   * CloudFormation's `Definition` property rather than `DefinitionString`:
+   * CFN accepts the definition as a native JSON value (verified against
+   * Floci — both forms round-trip), so a task's `Resource` can carry a
+   * `Ref`/`Fn::GetAtt` intrinsic — e.g. `Resource: someFunc.Arn` — directly,
+   * with no `Fn::Sub` string templating needed to splice ARNs into a JSON
+   * string. Same `Value<T>`-over-string-building bias as #1366, one level up.
+   */
+  definition: Record<string, unknown>;
+  /** ARNs of the Lambda functions this workflow's tasks invoke; grants `lambda:InvokeFunction` on each. */
+  lambdaFunctionArns?: Value<string>[];
+  stateMachineType?: "STANDARD" | "EXPRESS";
+  /** CloudWatch Logs retention for the auto-created log group. Default 14. */
+  logRetentionDays?: number;
+  /** `LoggingConfiguration` level. Default `"ALL"` — set `"OFF"` to skip execution logging. */
+  loggingLevel?: "ALL" | "ERROR" | "FATAL" | "OFF";
+  ManagedPolicyArns?: string[];
+  Policies?: InstanceType<typeof Role_Policy>[];
+  defaults?: {
+    role?: Partial<ConstructorParameters<typeof Role>[0]>;
+    logGroup?: Partial<ConstructorParameters<typeof LogGroup>[0]>;
+    stateMachine?: Partial<ConstructorParameters<typeof StateMachine>[0]>;
+  };
+}
+
+export const StepFunctionsWorkflow = Composite((props: StepFunctionsWorkflowProps) => {
+  const { defaults } = props;
+
+  const logGroup = new LogGroup(mergeDefaults({
+    RetentionInDays: props.logRetentionDays ?? 14,
+  }, defaults?.logGroup));
+
+  const logDeliveryPolicy = new Role_Policy({
+    PolicyName: "StepFunctionsLogDelivery",
+    PolicyDocument: logDeliveryPolicyDocument,
+  });
+
+  const invokePolicyDocument = {
+    Version: "2012-10-17" as const,
+    Statement: [{ Effect: "Allow" as const, Action: LambdaActions.Invoke, Resource: props.lambdaFunctionArns }],
+  };
+
+  // Conditional entry via spread keeps the `new` out of the `if` (EVL002).
+  const invokePolicies = props.lambdaFunctionArns && props.lambdaFunctionArns.length > 0
+    ? [new Role_Policy({ PolicyName: "InvokeLambdaTasks", PolicyDocument: invokePolicyDocument })]
+    : [];
+
+  const policies = [logDeliveryPolicy, ...invokePolicies, ...(props.Policies ?? [])];
+
+  const role = new Role(mergeDefaults({
+    AssumeRolePolicyDocument: stepFunctionsTrustPolicy,
+    ManagedPolicyArns: props.ManagedPolicyArns,
+    Policies: policies,
+  }, defaults?.role));
+
+  const loggingConfiguration = new StateMachine_LoggingConfiguration({
+    Destinations: [
+      new StateMachine_LogDestination({
+        CloudWatchLogsLogGroup: new StateMachine_CloudWatchLogsLogGroup({ LogGroupArn: logGroup.Arn }),
+      }),
+    ],
+    IncludeExecutionData: true,
+    Level: props.loggingLevel ?? "ALL",
+  });
+
+  const stateMachine = new StateMachine(mergeDefaults({
+    StateMachineName: props.name,
+    RoleArn: role.Arn,
+    Definition: props.definition,
+    StateMachineType: props.stateMachineType ?? "STANDARD",
+    LoggingConfiguration: loggingConfiguration,
+  }, defaults?.stateMachine));
+
+  return { role, logGroup, stateMachine };
+}, "StepFunctionsWorkflow");

package/src/deep-observe.test.ts

@@ -25,9 +25,10 @@ const {
   awsDeepNormalizationHooks,
   hasOwnershipMarker,
   schemaReadOnlyPatterns,
+  outOfBandChildName,
 } = await import("./deep-observe");
 const { parseResourceDescription } = await import("./api/read-client");
-const { deepDiffForLexicon } = await import("@intentius/chant/lifecycle/deep-observe");
+const { deepDiffForLexicon, diffDeepObservation } = await import("@intentius/chant/lifecycle/deep-observe");
 const { normalizeDeepObservation, normalizeDeepProperties, flattenDeepProperties } = await import("@intentius/chant/deep-observation");
 
 const ok = (text: string) => ({ status: 200, text });
@@ -598,6 +599,205 @@ describe("observeResourcesDeepAws", () => {
   });
 });
 
+/**
+ * The out-of-band pass (#1015): child resources that exist live under a
+ * declared parent and correspond to nothing in the stack, in the estate, or
+ * in source — the console-added SNS subscription and inline role policy the
+ * issue names. Cloud Control's `ListResources` is scoped to one parent by
+ * `ResourceModel`, and everything the listing returns is sorted into
+ * declared or out-of-band.
+ */
+describe("out-of-band children (#1015)", () => {
+  /** A Cloud Control `ListResources` body — each model a JSON string, like `GetResource`. */
+  const list = (descriptions: Array<[string, Record<string, unknown>]>) =>
+    ok(
+      JSON.stringify({
+        ResourceDescriptions: descriptions.map(([id, props]) => ({
+          Identifier: id,
+          Properties: JSON.stringify(props),
+        })),
+      }),
+    );
+
+  test("a console-added inline policy surfaces as an entity nobody declared", async () => {
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) {
+        return stackResources([
+          ["AppRole", "AWS::IAM::Role", "app-role"],
+          // The stack's own inline policy, deployed under its Cloud Control
+          // identifier (`PolicyName|RoleName`, the schema's own order).
+          ["Inline", "AWS::IAM::RolePolicy", "declared-pol|app-role"],
+        ]);
+      }
+      if (call.target === "CloudApiService.ListResources") {
+        return list([
+          ["declared-pol|app-role", { RoleName: "app-role", PolicyName: "declared-pol" }],
+          [
+            "debug-access|app-role",
+            {
+              RoleName: "app-role",
+              PolicyName: "debug-access",
+              PolicyDocument: { Statement: [{ Sid: "Debug", Effect: "Allow", Action: ["s3:*"], Resource: "*" }] },
+            },
+          ],
+        ]);
+      }
+      return cloudControl("app-role", { RoleName: "app-role" });
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["AppRole", "Inline"], http: fake.http }),
+    );
+
+    const name = outOfBandChildName("AWS::IAM::RolePolicy", "debug-access|app-role");
+    expect(result.resources[name]).toMatchObject({
+      type: "AWS::IAM::RolePolicy",
+      physicalId: "debug-access|app-role",
+    });
+    expect(result.resources[name].properties.PolicyName).toBe("debug-access");
+    // The stack's own inline policy is declared, not a finding.
+    expect(Object.keys(result.resources)).not.toContain(
+      outOfBandChildName("AWS::IAM::RolePolicy", "declared-pol|app-role"),
+    );
+    // The listing was scoped to the parent the stack read resolved.
+    const listing = fake.calls.find((c) => c.target === "CloudApiService.ListResources");
+    expect(JSON.parse(listing?.body ?? "{}")).toEqual({
+      TypeName: "AWS::IAM::RolePolicy",
+      ResourceModel: JSON.stringify({ RoleName: "app-role" }),
+    });
+  });
+
+  test("a console-added SNS subscription surfaces even though the topic has no deep reader", async () => {
+    const topicArn = "arn:aws:sns:us-east-1:111122223333:alerts";
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) {
+        return stackResources([
+          ["Alerts", "AWS::SNS::Topic", topicArn],
+          ["Mail", "AWS::SNS::Subscription", `${topicArn}:5d5a2c73`],
+        ]);
+      }
+      if (call.target === "CloudApiService.ListResources") {
+        return list([
+          [`${topicArn}:5d5a2c73`, { TopicArn: topicArn, Protocol: "email" }],
+          [`${topicArn}:rogue`, { TopicArn: topicArn, Protocol: "https", Endpoint: "https://n.example" }],
+        ]);
+      }
+      return apiError("ValidationException", "nothing else should be read");
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["Alerts", "Mail"], http: fake.http }),
+    );
+
+    // The topic itself stays a hole — no deep reader — but the listing under
+    // it needs only the physical id the stack already resolved.
+    expect(result.unobserved.Alerts?.reason).toBe("unsupported-kind");
+    expect(Object.keys(result.resources)).toEqual([
+      outOfBandChildName("AWS::SNS::Subscription", `${topicArn}:rogue`),
+    ]);
+  });
+
+  test("a legacy AWS::IAM::Policy attachment is declared, not out-of-band", async () => {
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) {
+        return stackResources([
+          ["AppRole", "AWS::IAM::Role", "app-role"],
+          // The legacy inline form: its physical id is the policy name, which
+          // is the first part of the RolePolicy identifier the listing returns.
+          ["LegacyPol", "AWS::IAM::Policy", "stack-legacypol-1ABC"],
+        ]);
+      }
+      if (call.target === "CloudApiService.ListResources") {
+        return list([["stack-legacypol-1ABC|app-role", { RoleName: "app-role", PolicyName: "stack-legacypol-1ABC" }]]);
+      }
+      return cloudControl("app-role", { RoleName: "app-role" });
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["AppRole", "LegacyPol"], http: fake.http }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["AppRole"]);
+  });
+
+  test("an identity spelled in source counts as declared before it reaches any stack", async () => {
+    // The carve case: the policy is declared, its identity is spelled in
+    // props, and no stack carries it yet. Listing it is not a finding.
+    const declared = entities({
+      AppRole: { entityType: "AWS::IAM::Role", props: { RoleName: "app-role" } },
+      Carved: { entityType: "AWS::IAM::RolePolicy", props: { RoleName: "app-role", PolicyName: "carved" } },
+    });
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) return stackResources([["AppRole", "AWS::IAM::Role", "app-role"]]);
+      if (call.target === "CloudApiService.ListResources") {
+        return list([["carved|app-role", { RoleName: "app-role", PolicyName: "carved" }]]);
+      }
+      return cloudControl("app-role", { RoleName: "app-role" });
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({
+        environment: "prod",
+        entityNames: ["AppRole", "Carved"],
+        entities: declared,
+        http: fake.http,
+      }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["AppRole"]);
+  });
+
+  test("a failed child listing is silence about children, never a fabricated finding", async () => {
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) return stackResources([["AppRole", "AWS::IAM::Role", "app-role"]]);
+      if (call.target === "CloudApiService.ListResources") {
+        // Floci's answer for an operation it does not serve.
+        return apiError("UnsupportedOperation", "ListResources is not supported for AWS::IAM::RolePolicy");
+      }
+      return cloudControl("app-role", { RoleName: "app-role" });
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["AppRole"], http: fake.http }),
+    );
+    expect(Object.keys(result.resources)).toEqual(["AppRole"]);
+    expect(result.unobserved).toEqual({});
+  });
+
+  test("--owned: a withheld parent keeps its children out of the report too", async () => {
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) return stackResources([["AppRole", "AWS::IAM::Role", "app-role"]]);
+      if (call.target === "CloudApiService.ListResources") {
+        return list([["debug-access|app-role", { RoleName: "app-role", PolicyName: "debug-access" }]]);
+      }
+      // No ownership tag: the parent is not chant's.
+      return cloudControl("app-role", { RoleName: "app-role" });
+    });
+    const result = normalizeDeepObservation(
+      await observeResourcesDeepAws({ environment: "prod", entityNames: ["AppRole"], owned: true, http: fake.http }),
+    );
+    expect(result.unobserved.AppRole?.reason).toBe("filtered");
+    expect(Object.keys(result.resources)).toEqual([]);
+    expect(fake.calls.some((c) => c.target === "CloudApiService.ListResources")).toBe(false);
+  });
+
+  test("the deep diff reports the child as an undeclared entity, and the declared estate stays clean", async () => {
+    const declared = entities({ AppRole: { entityType: "AWS::IAM::Role", props: { RoleName: "app-role" } } });
+    const fake = httpFake((_identifier, call) => {
+      if (!call.target) return stackResources([["AppRole", "AWS::IAM::Role", "app-role"]]);
+      if (call.target === "CloudApiService.ListResources") {
+        return list([["debug-access|app-role", { RoleName: "app-role", PolicyName: "debug-access" }]]);
+      }
+      return cloudControl("app-role", { RoleName: "app-role" });
+    });
+    const live = normalizeDeepObservation(
+      await observeResourcesDeepAws({
+        environment: "prod",
+        entityNames: ["AppRole"],
+        entities: declared,
+        http: fake.http,
+      }),
+    );
+    const result = diffDeepObservation(declared, live, awsDeepNormalizationHooks);
+    expect(result.undeclaredEntities).toEqual([outOfBandChildName("AWS::IAM::RolePolicy", "debug-access|app-role")]);
+    expect(result.unchanged).toEqual(["AppRole"]);
+    expect(result.drifted).toEqual([]);
+  });
+});
+
 /**
  * The acceptance test for #1015: the real plugin, a mutated live tree, a
  * baseline, and exactly the genuine drift.