alchemy 2.0.0-beta.55 → 2.0.0-beta.57

package/src/AWS/CloudFront/Distribution.ts

@@ -2,6 +2,8 @@ import * as cloudfront from "@distilled.cloud/aws/cloudfront";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
+import { isResolved } from "../../Diff.ts";
 import type { Input } from "../../Input.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
@@ -44,6 +46,14 @@ export interface DistributionOrigin {
    * @default false
    */
   s3Origin?: boolean;
+  /**
+   * Explicit S3 origin settings (legacy Origin Access Identity, read timeout).
+   * When set, the origin is treated as an S3 origin regardless of `s3Origin`.
+   */
+  s3OriginConfig?: {
+    originAccessIdentity?: string;
+    originReadTimeout?: number;
+  };
   /**
    * Optional custom origin settings.
    */
@@ -54,7 +64,50 @@ export interface DistributionOrigin {
     originReadTimeout?: number;
     originKeepaliveTimeout?: number;
     originSslProtocols?: cloudfront.SslProtocol[];
+    /**
+     * IP address type CloudFront uses to connect to the origin.
+     */
+    ipAddressType?: cloudfront.IpAddressType;
+    /**
+     * Mutual TLS configuration for the origin connection.
+     */
+    originMtlsConfig?: {
+      clientCertificateArn: string;
+    };
+  };
+  /**
+   * Route this origin through a VPC origin (private ALB/NLB/EC2). Mutually
+   * exclusive with `s3Origin`/`s3OriginConfig`/`customOriginConfig`.
+   */
+  vpcOriginConfig?: {
+    vpcOriginId: Input<string>;
+    originReadTimeout?: number;
+    originKeepaliveTimeout?: number;
+    ownerAccountId?: string;
   };
+  /**
+   * Custom headers CloudFront adds to every request it sends to the origin.
+   */
+  customHeaders?: Record<string, string>;
+  /**
+   * Origin Shield configuration.
+   */
+  originShield?: {
+    enabled: boolean;
+    originShieldRegion?: string;
+  };
+  /**
+   * Number of times CloudFront attempts to connect to the origin (1-3).
+   */
+  connectionAttempts?: number;
+  /**
+   * Seconds CloudFront waits when trying to establish a connection (1-10).
+   */
+  connectionTimeout?: number;
+  /**
+   * Seconds CloudFront waits for the origin to deliver a complete response.
+   */
+  responseCompletionTimeout?: number;
 }
 
 export interface DistributionBehavior {
@@ -79,6 +132,32 @@ export interface DistributionBehavior {
     eventType: cloudfront.EventType;
     includeBody?: boolean;
   }[];
+  /**
+   * CloudFront KeyGroup IDs whose public keys gate signed URLs/cookies.
+   */
+  trustedKeyGroups?: Input<string[]>;
+  /**
+   * Legacy trusted signer AWS account numbers for signed URLs/cookies.
+   */
+  trustedSigners?: string[];
+  /**
+   * Field-level encryption configuration ID.
+   */
+  fieldLevelEncryptionId?: string;
+  /**
+   * ARN of a real-time log configuration to attach.
+   */
+  realtimeLogConfigArn?: string;
+  /**
+   * Whether Microsoft Smooth Streaming is enabled for this behavior.
+   */
+  smoothStreaming?: boolean;
+  /**
+   * gRPC configuration for this behavior.
+   */
+  grpcConfig?: {
+    enabled: boolean;
+  };
 }
 
 export interface DistributionViewerCertificate {
@@ -86,6 +165,68 @@ export interface DistributionViewerCertificate {
   acmCertificateArn?: string;
   sslSupportMethod?: cloudfront.SSLSupportMethod;
   minimumProtocolVersion?: cloudfront.MinimumProtocolVersion;
+  /**
+   * Legacy IAM certificate ID.
+   */
+  iamCertificateId?: string;
+  /**
+   * Legacy certificate identifier (IAM/ACM raw value).
+   */
+  certificate?: string;
+  /**
+   * Source of the legacy certificate.
+   */
+  certificateSource?: cloudfront.CertificateSource;
+}
+
+export interface DistributionGeoRestriction {
+  /**
+   * Restriction mode. `none` disables geo restriction.
+   */
+  restrictionType: cloudfront.GeoRestrictionType;
+  /**
+   * Two-letter ISO 3166-1 country codes the restriction applies to.
+   */
+  locations?: string[];
+}
+
+export interface DistributionLogging {
+  /**
+   * Whether access logging is enabled.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Whether cookies are included in access logs.
+   */
+  includeCookies?: boolean;
+  /**
+   * S3 bucket (domain name) that receives access logs.
+   */
+  bucket?: string;
+  /**
+   * Prefix applied to access log object keys.
+   */
+  prefix?: string;
+}
+
+export interface DistributionOriginGroup {
+  /**
+   * Origin group identifier (target it from a cache behavior).
+   */
+  id: string;
+  /**
+   * Member origin IDs in failover order (primary first, secondary second).
+   */
+  members: string[];
+  /**
+   * HTTP status codes that trigger failover to the next member.
+   */
+  failoverStatusCodes: number[];
+  /**
+   * How CloudFront selects the origin within the group.
+   */
+  selectionCriteria?: cloudfront.OriginGroupSelectionCriteria;
 }
 
 const isFunctionAssociationPending = (error: cloudfront.InvalidArgument) => {
@@ -158,6 +299,32 @@ export interface DistributionProps {
    * @default true
    */
   isIpv6Enabled?: boolean;
+  /**
+   * Geographic distribution restrictions. Defaults to no restriction.
+   */
+  geoRestriction?: DistributionGeoRestriction;
+  /**
+   * Standard access logging configuration.
+   */
+  logging?: DistributionLogging;
+  /**
+   * Origin failover groups. Target a group id from a cache behavior's
+   * `targetOriginId`.
+   */
+  originGroups?: Input<DistributionOriginGroup[]>;
+  /**
+   * Continuous deployment policy ID for blue/green deployments.
+   */
+  continuousDeploymentPolicyId?: string;
+  /**
+   * Whether this is a staging distribution for blue/green deployments.
+   * Create-only — changing it forces a replacement.
+   */
+  staging?: boolean;
+  /**
+   * Anycast static IP list ID to associate with the distribution.
+   */
+  anycastIpListId?: string;
   /**
    * User-defined tags to apply to the distribution.
    */
@@ -227,7 +394,7 @@ export interface Distribution extends Resource<
  * `Distribution` manages the CDN layer for static sites and HTTP origins such
  * as Lambda Function URLs and ALBs. It exposes the distribution domain and
  * hosted zone ID needed for Route 53 alias records.
- *
+ * @resource
  * @section Creating Distributions
  * @example Private S3 Origin
  * ```typescript
@@ -448,6 +615,16 @@ export const DistributionProvider = () =>
           "domainName",
           "hostedZoneId",
         ],
+        // `Staging` is create-only at the CloudFront API level; toggling it
+        // requires a fresh distribution. Everything else updates in place via
+        // the whole-config `updateDistribution` PUT.
+        diff: Effect.fn(function* ({ olds, news: _news }) {
+          if (!isResolved(_news)) return undefined;
+          const news = _news as DistributionProps;
+          if ((olds?.staging ?? false) !== (news.staging ?? false)) {
+            return { action: "replace" } as const;
+          }
+        }),
         read: Effect.fn(function* ({ output }) {
           if (!output?.distributionId) {
             return undefined;
@@ -460,6 +637,59 @@ export const DistributionProvider = () =>
 
           return toAttrs(current.distribution, current.etag, current.tags);
         }),
+        // CloudFront is a global service (no region). Enumerate every
+        // distribution in the account via the paginated `listDistributions`
+        // op, then resolve each summary to the full `read`-shaped Attributes
+        // (distribution + config + tags) so callers get a `delete`-ready item.
+        list: () =>
+          Effect.gen(function* () {
+            const summaries = yield* cloudfront.listDistributions
+              .pages({})
+              .pipe(
+                Stream.runCollect,
+                Effect.map((chunk) =>
+                  Array.from(chunk).flatMap(
+                    (page) => page.DistributionList?.Items ?? [],
+                  ),
+                ),
+              );
+
+            const rows = yield* Effect.forEach(
+              summaries,
+              (summary) =>
+                getCurrent(summary.Id).pipe(
+                  // Hydrating every distribution fires three read calls each
+                  // (getDistribution + getDistributionConfig +
+                  // listTagsForResource). Across a busy account that trips
+                  // CloudFront's low read throttle, so ride it out.
+                  Effect.retry({
+                    while: (error) => error._tag === "ThrottlingException",
+                    // Steady, capped backoff: CloudFront's read throttle
+                    // resets quickly, so a fixed cadence drains far faster
+                    // than an exponential whose tail delay can balloon past
+                    // the test budget on a busy account.
+                    schedule: Schedule.spaced("1 second").pipe(
+                      Schedule.jittered,
+                      Schedule.both(Schedule.recurs(30)),
+                    ),
+                  }),
+                  Effect.map((current) =>
+                    current
+                      ? toAttrs(
+                          current.distribution,
+                          current.etag,
+                          current.tags,
+                        )
+                      : undefined,
+                  ),
+                ),
+              { concurrency: 10 },
+            );
+
+            return rows.filter(
+              (row): row is Distribution["Attributes"] => row !== undefined,
+            );
+          }),
         reconcile: Effect.fn(function* ({
           id,
           instanceId,
@@ -815,6 +1045,26 @@ const toBehavior = (
   MinTTL: behavior.minTtl,
   DefaultTTL: behavior.defaultTtl,
   MaxTTL: behavior.maxTtl,
+  TrustedKeyGroups: behavior.trustedKeyGroups
+    ? {
+        Enabled: (behavior.trustedKeyGroups as string[]).length > 0,
+        Quantity: (behavior.trustedKeyGroups as string[]).length,
+        Items: behavior.trustedKeyGroups as string[],
+      }
+    : undefined,
+  TrustedSigners: behavior.trustedSigners
+    ? {
+        Enabled: behavior.trustedSigners.length > 0,
+        Quantity: behavior.trustedSigners.length,
+        Items: behavior.trustedSigners,
+      }
+    : undefined,
+  FieldLevelEncryptionId: behavior.fieldLevelEncryptionId,
+  RealtimeLogConfigArn: behavior.realtimeLogConfigArn,
+  SmoothStreaming: behavior.smoothStreaming,
+  GrpcConfig: behavior.grpcConfig
+    ? { Enabled: behavior.grpcConfig.enabled }
+    : undefined,
   FunctionAssociations: behavior.functionAssociations
     ? {
         Quantity: behavior.functionAssociations.length,
@@ -836,30 +1086,83 @@ const toBehavior = (
     : undefined,
 });
 
-const toOrigin = (origin: DistributionOrigin): cloudfront.Origin => ({
-  Id: origin.id,
-  DomainName: origin.domainName as string,
-  OriginPath: origin.originPath as string | undefined,
-  OriginAccessControlId: origin.originAccessControlId as string | undefined,
-  S3OriginConfig: origin.s3Origin ? { OriginAccessIdentity: "" } : undefined,
-  CustomOriginConfig: origin.s3Origin
-    ? undefined
-    : {
-        HTTPPort: origin.customOriginConfig?.httpPort ?? 80,
-        HTTPSPort: origin.customOriginConfig?.httpsPort ?? 443,
-        OriginProtocolPolicy:
-          origin.customOriginConfig?.originProtocolPolicy ?? "https-only",
-        OriginSslProtocols: {
-          Quantity: (
-            origin.customOriginConfig?.originSslProtocols ?? ["TLSv1.2"]
-          ).length,
-          Items: origin.customOriginConfig?.originSslProtocols ?? ["TLSv1.2"],
-        },
-        OriginReadTimeout: origin.customOriginConfig?.originReadTimeout,
-        OriginKeepaliveTimeout:
-          origin.customOriginConfig?.originKeepaliveTimeout,
-      },
-});
+const toOrigin = (origin: DistributionOrigin): cloudfront.Origin => {
+  // Exactly one of the three origin-config shapes may be set. A VPC origin
+  // wins, then an explicit/legacy S3 origin, otherwise a custom origin.
+  const isVpcOrigin = origin.vpcOriginConfig !== undefined;
+  const isS3Origin =
+    !isVpcOrigin &&
+    (origin.s3Origin === true || origin.s3OriginConfig !== undefined);
+
+  return {
+    Id: origin.id,
+    DomainName: origin.domainName as string,
+    OriginPath: origin.originPath as string | undefined,
+    OriginAccessControlId: origin.originAccessControlId as string | undefined,
+    CustomHeaders: origin.customHeaders
+      ? {
+          Quantity: Object.keys(origin.customHeaders).length,
+          Items: Object.entries(origin.customHeaders).map(([name, value]) => ({
+            HeaderName: name,
+            HeaderValue: value,
+          })),
+        }
+      : undefined,
+    OriginShield: origin.originShield
+      ? {
+          Enabled: origin.originShield.enabled,
+          OriginShieldRegion: origin.originShield.originShieldRegion,
+        }
+      : undefined,
+    ConnectionAttempts: origin.connectionAttempts,
+    ConnectionTimeout: origin.connectionTimeout,
+    ResponseCompletionTimeout: origin.responseCompletionTimeout,
+    VpcOriginConfig: isVpcOrigin
+      ? {
+          VpcOriginId: origin.vpcOriginConfig!.vpcOriginId as string,
+          OwnerAccountId: origin.vpcOriginConfig!.ownerAccountId,
+          OriginReadTimeout: origin.vpcOriginConfig!.originReadTimeout,
+          OriginKeepaliveTimeout:
+            origin.vpcOriginConfig!.originKeepaliveTimeout,
+        }
+      : undefined,
+    S3OriginConfig: isS3Origin
+      ? {
+          OriginAccessIdentity:
+            origin.s3OriginConfig?.originAccessIdentity ?? "",
+          OriginReadTimeout: origin.s3OriginConfig?.originReadTimeout,
+        }
+      : undefined,
+    CustomOriginConfig:
+      isVpcOrigin || isS3Origin
+        ? undefined
+        : {
+            HTTPPort: origin.customOriginConfig?.httpPort ?? 80,
+            HTTPSPort: origin.customOriginConfig?.httpsPort ?? 443,
+            OriginProtocolPolicy:
+              origin.customOriginConfig?.originProtocolPolicy ?? "https-only",
+            OriginSslProtocols: {
+              Quantity: (
+                origin.customOriginConfig?.originSslProtocols ?? ["TLSv1.2"]
+              ).length,
+              Items: origin.customOriginConfig?.originSslProtocols ?? [
+                "TLSv1.2",
+              ],
+            },
+            OriginReadTimeout: origin.customOriginConfig?.originReadTimeout,
+            OriginKeepaliveTimeout:
+              origin.customOriginConfig?.originKeepaliveTimeout,
+            IpAddressType: origin.customOriginConfig?.ipAddressType,
+            OriginMtlsConfig: origin.customOriginConfig?.originMtlsConfig
+              ? {
+                  ClientCertificateArn:
+                    origin.customOriginConfig.originMtlsConfig
+                      .clientCertificateArn,
+                }
+              : undefined,
+          },
+  };
+};
 
 const toConfig = (
   callerReference: string,
@@ -898,6 +1201,27 @@ const toConfig = (
         ) as cloudfront.CacheBehavior[],
       }
     : undefined,
+  OriginGroups: props.originGroups
+    ? {
+        Quantity: (props.originGroups as DistributionOriginGroup[]).length,
+        Items: (props.originGroups as DistributionOriginGroup[]).map(
+          (group) => ({
+            Id: group.id,
+            FailoverCriteria: {
+              StatusCodes: {
+                Quantity: group.failoverStatusCodes.length,
+                Items: group.failoverStatusCodes,
+              },
+            },
+            Members: {
+              Quantity: group.members.length,
+              Items: group.members.map((originId) => ({ OriginId: originId })),
+            },
+            SelectionCriteria: group.selectionCriteria,
+          }),
+        ),
+      }
+    : undefined,
   CustomErrorResponses: props.customErrorResponses
     ? {
         Quantity: (
@@ -907,12 +1231,23 @@ const toConfig = (
       }
     : undefined,
   Comment: props.comment ?? "",
+  Logging: props.logging
+    ? {
+        Enabled: props.logging.enabled ?? true,
+        IncludeCookies: props.logging.includeCookies ?? false,
+        Bucket: props.logging.bucket ?? "",
+        Prefix: props.logging.prefix ?? "",
+      }
+    : undefined,
   Enabled: props.enabled ?? true,
   ViewerCertificate: props.viewerCertificate
     ? {
         CloudFrontDefaultCertificate: (
           props.viewerCertificate as DistributionViewerCertificate
         ).cloudFrontDefaultCertificate,
+        IAMCertificateId: (
+          props.viewerCertificate as DistributionViewerCertificate
+        ).iamCertificateId,
         ACMCertificateArn: (
           props.viewerCertificate as DistributionViewerCertificate
         ).acmCertificateArn,
@@ -922,22 +1257,38 @@ const toConfig = (
         MinimumProtocolVersion: (
           props.viewerCertificate as DistributionViewerCertificate
         ).minimumProtocolVersion,
+        Certificate: (props.viewerCertificate as DistributionViewerCertificate)
+          .certificate,
+        CertificateSource: (
+          props.viewerCertificate as DistributionViewerCertificate
+        ).certificateSource,
       }
     : props.aliases && props.aliases.length > 0
       ? undefined
       : {
           CloudFrontDefaultCertificate: true,
         },
-  Restrictions: {
-    GeoRestriction: {
-      RestrictionType: "none",
-      Quantity: 0,
-    },
-  },
+  Restrictions: props.geoRestriction
+    ? {
+        GeoRestriction: {
+          RestrictionType: props.geoRestriction.restrictionType,
+          Quantity: props.geoRestriction.locations?.length ?? 0,
+          Items: props.geoRestriction.locations,
+        },
+      }
+    : {
+        GeoRestriction: {
+          RestrictionType: "none",
+          Quantity: 0,
+        },
+      },
   PriceClass: props.priceClass,
   WebACLId: props.webAclId,
   HttpVersion: props.httpVersion ?? "http2",
   IsIPV6Enabled: props.isIpv6Enabled ?? true,
+  ContinuousDeploymentPolicyId: props.continuousDeploymentPolicyId,
+  Staging: props.staging,
+  AnycastIpListId: props.anycastIpListId,
 });
 
 const toAttrs = (

package/src/AWS/CloudFront/Function.ts

@@ -82,7 +82,7 @@ export interface Function extends Resource<
  *
  * CloudFront Functions are lightweight JavaScript handlers that run at the
  * edge and can be attached to distribution cache behaviors.
- *
+ * @resource
  * @section Creating Functions
  * @example Viewer Request Function
  * ```typescript
@@ -153,6 +153,24 @@ export const FunctionProvider = () =>
 
       return {
         stables: ["functionArn", "functionName"],
+        // CloudFront is global; listFunctions enumerates every function in the
+        // account. It is non-paginated in distilled but uses Marker/NextMarker,
+        // so we page manually until NextMarker is absent. All CloudFront
+        // functions are custom (no AWS-managed ones), so every item is ours.
+        list: () =>
+          Effect.gen(function* () {
+            const items: Function["Attributes"][] = [];
+            let marker: string | undefined = undefined;
+            do {
+              const listed: cloudfront.ListFunctionsResult =
+                yield* cloudfront.listFunctions({ Marker: marker });
+              for (const summary of listed.FunctionList?.Items ?? []) {
+                items.push(toAttrs(summary, undefined, summary.Name ?? ""));
+              }
+              marker = listed.FunctionList?.NextMarker;
+            } while (marker);
+            return items;
+          }),
         diff: Effect.fn(function* ({ id, olds, news: _news }) {
           if (!isResolved(_news)) return undefined;
           const news = _news as typeof olds;
@@ -359,7 +377,7 @@ const toAttrs = (
   functionArn: summary.FunctionMetadata.FunctionARN,
   functionName: summary.Name || fallbackName,
   runtime: summary.FunctionConfig.Runtime,
-  comment: summary.FunctionConfig.Comment,
+  comment: summary.FunctionConfig.Comment ?? "",
   stage: summary.FunctionMetadata.Stage ?? "DEVELOPMENT",
   status: summary.Status ?? "UNKNOWN",
   lastModifiedTime: summary.FunctionMetadata.LastModifiedTime,

package/src/AWS/CloudFront/Invalidation.ts

@@ -49,7 +49,7 @@ export interface Invalidation extends Resource<
  *
  * `Invalidation` is a helper resource for website deployments that need to
  * clear selected CloudFront cache paths after asset updates.
- *
+ * @resource
  * @section Creating Invalidations
  * @example Invalidate The Entire Distribution
  * ```typescript
@@ -155,6 +155,12 @@ export const InvalidationProvider = () =>
 
       return {
         stables: ["distributionId", "version"],
+        // Non-listable: an Invalidation is an ephemeral, immutable ledger entry
+        // keyed by {distributionId, invalidationId}. It completes on its own and
+        // cannot be deleted (`delete` is a no-op), so there is no persistent
+        // "current resource" to enumerate for nuke. `listInvalidations` only
+        // exposes historical, undeletable entries per distribution.
+        list: () => Effect.succeed([]),
         diff: Effect.fn(function* ({ olds, news: _news }) {
           if (!isResolved(_news)) return undefined;
           const news = _news as typeof olds;

package/src/AWS/CloudFront/KeyGroup.ts

@@ -62,7 +62,7 @@ export interface KeyGroup extends Resource<
  * `TrustedKeyGroups` on a Distribution's cache behavior. CloudFront uses
  * the keys in the group to verify the signatures on signed URLs and
  * signed cookies for that behavior.
- *
+ * @resource
  * @section Creating Key Groups
  * @example Group two public keys for signed URL verification
  * ```typescript
@@ -132,6 +132,26 @@ export const KeyGroupProvider = () =>
 
       return {
         stables: ["keyGroupId"],
+        list: () =>
+          Effect.gen(function* () {
+            const items: ReturnType<typeof toAttrs>[] = [];
+            let marker: string | undefined = undefined;
+            do {
+              const listed: cloudfront.ListKeyGroupsResult =
+                yield* cloudfront.listKeyGroups({ Marker: marker });
+              for (const summary of listed.KeyGroupList?.Items ?? []) {
+                const id = summary.KeyGroup?.Id;
+                const config = summary.KeyGroup?.KeyGroupConfig;
+                if (!id || !config) continue;
+                // The list summary omits the ETag; re-read each group to
+                // produce the exact Attributes shape `read` returns.
+                const found = yield* getById(id);
+                items.push(toAttrs(id, found?.config ?? config, found?.etag));
+              }
+              marker = listed.KeyGroupList?.NextMarker;
+            } while (marker);
+            return items;
+          }),
         diff: Effect.fn(function* ({ id, news, olds }) {
           if (!isResolved(news)) return undefined;
           if (

package/src/AWS/CloudFront/KeyValueStore.ts

@@ -1,5 +1,6 @@
 import * as cloudfront from "@distilled.cloud/aws/cloudfront";
 import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
 import { isResolved } from "../../Diff.ts";
 import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
@@ -59,7 +60,7 @@ export interface KeyValueStore extends Resource<
  *
  * KeyValueStores can be associated with CloudFront Functions and are useful for
  * routing metadata or other small edge-time lookup tables.
- *
+ * @resource
  * @section Creating KeyValueStores
  * @example Basic Store
  * ```typescript
@@ -118,6 +119,20 @@ export const KeyValueStoreProvider = () =>
           }
           return toAttrs(current.KeyValueStore, current.ETag, name);
         }),
+        // CloudFront is global; `listKeyValueStores` enumerates every store in
+        // the account. The list summary carries no ETag, so it's undefined here
+        // (matches the `etag: string | undefined` attribute).
+        list: () =>
+          cloudfront.listKeyValueStores.pages({}).pipe(
+            Stream.runCollect,
+            Effect.map((chunk) =>
+              Array.from(chunk).flatMap((page) =>
+                (page.KeyValueStoreList?.Items ?? []).map((store) =>
+                  toAttrs(store, undefined, store.Name),
+                ),
+              ),
+            ),
+          ),
         reconcile: Effect.fn(function* ({ id, news, output, session }) {
           const name =
             output?.keyValueStoreName ?? (yield* createName(id, news));

package/src/AWS/CloudFront/KvEntries.ts

@@ -45,7 +45,7 @@ export interface KvEntries extends Resource<
  * Entries are stored with a `{namespace}:{key}` prefix to allow multiple
  * logical groups within a single store. Updates use batched optimistic
  * concurrency with automatic ETag retry.
- *
+ * @resource
  * @section Managing Entries
  * @example Basic Entries
  * ```typescript
@@ -195,6 +195,11 @@ export const KvEntriesProvider = () =>
       });
 
       return {
+        // Non-listable: a KvEntries resource is a logical group of key/value
+        // data keyed entirely by its parent store ARN + namespace (both chosen
+        // by the user). There is no account-wide API to enumerate these groups,
+        // and the entries are managed content rather than nuke-able infra.
+        list: () => Effect.succeed([]),
         read: withKvsRegionFn(
           Effect.fn(function* ({ output }) {
             return output;