AUTOMATIC FRESHNESS WITH ONE-YEAR CACHING
Build: 2026-07-14_v032

GOAL
Keep HTML, JSON directory indexes, images, video, scripts, and other website objects cached for one year, while automatically removing only stale CloudFront entries whenever S3 content changes.

WHAT V032 FIXES
The previous event-coalescing lock could rebuild too early during a multi-file upload. The first event waited seven seconds and rebuilt, while later events saw the active lock and skipped their rebuild. That could leave .directory-index.json containing only the first files from an upload burst.

V032 uses a per-directory change signal:
1. Every S3 change updates a signal object for every affected directory.
2. One invocation owns the directory rebuild lock.
3. The owner waits until the signal remains unchanged for COALESCE_DELAY_MS.
4. It rebuilds .directory-index.json.
5. If another change arrived during the rebuild, it waits and rebuilds again.
6. Only after the final index is complete does it invalidate the exact directory routes.

AUTOMATIC PATH COVERAGE
An upload to:
  daily/2026-07-14/example.html
rebuilds and invalidates:
  /daily/2026-07-14
  /daily/2026-07-14/
  /daily
  /daily/

An upload to:
  beta/_daily-builds/2026-07-14/example.html
rebuilds and invalidates:
  /beta/_daily-builds/2026-07-14
  /beta/_daily-builds/2026-07-14/
  /beta/_daily-builds
  /beta/_daily-builds/
  /beta
  /beta/

The changed object URL is also invalidated, which makes overwrites immediately fresh while newly named files remain maximally cacheable.

CACHE POLICY
Keep the existing one-year immutable cache settings. This update fixes event ordering and exact invalidation timing; it does not reduce cache duration.

DEPLOYMENT
1. Open the regional Lambda function used as the S3 directory-index updater.
2. Replace its index.mjs with:
   s3-directory-index-updater/index.mjs
3. Deploy the function. This is a normal regional Lambda, not Lambda@Edge, so a CloudFront association/version update is not required.
4. Preserve these environment variables:
   ENABLE_EVENT_COALESCING=true
   COALESCE_DELAY_MS=7000
   ENABLE_CLOUDFRONT_INVALIDATION=true
   CLOUDFRONT_DISTRIBUTION_ID=<the distribution for that bucket/site>
5. Confirm the Lambda timeout is comfortably above the quiet window and rebuild time. 60 seconds or more is recommended; large trees may need longer.
6. Confirm S3 ObjectCreated and ObjectRemoved notifications invoke this updater.
7. Confirm its role allows S3 List/Get/Head/Put/Delete and cloudfront:CreateInvalidation.

NO MANUAL INVALIDATIONS SHOULD BE NEEDED AFTER V032 IS DEPLOYED.