@exabugs/dynamodb-client 1.20.0 → 1.22.0

package/docs/NOTIFY.md

@@ -1,6 +1,6 @@
 # 運用通知（`@exabugs/dynamodb-client/notify`）
 
-ログ（`warn` 以上）・CloudWatch アラーム・直接呼び出しを、管理者へ通知するための**部品**。配線（購読フィルタ・Lambda・Terraform・秘密の置き場）は、各アプリが行う。既存の挙動は変えない（サブパス `./notify` の追加のみ）。
+ログ（`warn` 以上）・CloudWatch アラーム・直接呼び出しを、管理者へ通知するための**部品**。配線のうち、Lambda のエントリと秘密の置き場は各アプリが行う。購読フィルタ・Lambda・テーブルの Terraform は `terraform/ops-notify`（1.21.0）。既存の挙動は変えない（サブパス `./notify` の追加のみ）。
 
 ```text
 ログ(購読フィルタ) ─┐
@@ -119,6 +119,57 @@ export const handler = createNotifyHandler({
 });
 ```
 
+### 通知 Lambda のエントリ（`createOpsNotifyHandler`。1.22.0）
+
+`terraform/ops-notify` の Lambda のエントリは、ハンドラのファクトリを export するだけでよい。上の組み立て（環境変数の読み取り、Slack〔SSM の Webhook〕・メール〔SES v2〕のチャネル、通知ストア、管理者の一覧、alerts の記録）をライブラリが行う。asanowa・astro のエントリ（`functions/ops-notify/src/index.ts`・`apps/server/src/notify.ts`）を 1 つにしたもの:
+
+```ts
+import { createOpsNotifyHandler } from '@exabugs/dynamodb-client/notify/ops';
+
+export const handler = createOpsNotifyHandler();
+```
+
+- 環境変数（`terraform/ops-notify` が設定する。`readOpsNotifyConfig` が読む）: `PROJECT_NAME`・`ENV_NAME`・`RECORDS_IAM_URL`・`NOTICE_TABLE`（必須。無ければ `<名前> environment variable is required`）、`SLACK_WEBHOOK_PARAM`・`MAIL_FROM`（空なら、そのチャネルを作らない）、`SES_REGION`（既定 `us-east-1`）、`DRY_RUN=true`、`ADMIN_BASE_URL`（あるときだけ alerts に記録する）、`SKIP_RECORD_LOG_GROUPS`（カンマ区切り。`ADMIN_BASE_URL` があって空なら warn `ALERTS_SKIP_LOG_GROUPS_EMPTY`）。リージョンは `AWS_REGION`（無ければ `REGION`。どちらも無ければ例外）
+- ハンドラは最初の呼び出しで組み立て、コンテナの中で使い回す（遮断・管理者の一覧のキャッシュを保つ）。組み立てに失敗したら、次の呼び出しでやり直す
+- 既定: `failOnAnyChannelError: true`（一部のチャネルの失敗も Lambda の失敗先へ）、記録の上限 `OPS_NOTIFY_RECORD_LIMITS`（3000 ms・50 件・並列 5）、遮断 `OPS_NOTIFY_RECORD_BREAKER`（3 回・60 秒）、alerts の書き込みの HTTP の時間切れ `OPS_NOTIFY_RECORD_HTTP_TIMEOUT_MS`（2500 ms。記録の上限より短く）
+- Webhook の URL は SSM（SecureString）から最初の送信で読み、実行環境の間はキャッシュする
+- **サブパスは `notify/ops`**（`notify` 本体と分ける）。SSM・SES の SDK（`@aws-sdk/client-ssm`・`@aws-sdk/client-sesv2`。どちらもライブラリの依存）を静的に import するので、`notify` 本体（alerts-cleanup など）は SDK を読まないまま。メールの送信は、ライブラリが既定で SES v2 を使う（`sesSender` に SDK を渡す形は、`createNotifyHandler` を直接使うときのもの）
+- バンドル（どちらも CJS。`src/notify/ops/__tests__/bundle.test.ts` で固定）:
+  - SDK を外部にする（asanowa: `esbuild --bundle --platform=node --format=cjs --external:@aws-sdk/*`）: SDK は `require("@aws-sdk/…")` のまま残り、Lambda の実行環境の SDK（NODE_PATH）で解決される。動的 `import()` は残らない
+  - SDK も同梱する（astro: `--external` なし）: ライブラリの依存の版の SDK がバンドルに入る
+- alerts の書き込み先は Records のコレクション（`lazyCollection`。最初の書き込みで接続し、使い回す）。管理者の一覧は呼び出しごとに接続して閉じる（`withCollection`）
+
+オプション（どれも任意）:
+
+| オプション            | 既定                          | 内容                                                                                                                                                                                                    |
+| --------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `app`                 | `PROJECT_NAME`                | 通知の `app`。渡せば `PROJECT_NAME` は不要                                                                                                                                                              |
+| `region`              | `AWS_REGION`                  | 通知ストア・SSM・Records・ログ参照のリージョン                                                                                                                                                          |
+| `admins`              | 宛先は `id`、生のコレクション | `createAdminDirectory` の設定（`recipientFields`・`sortById`・`maxAdmins`・`collection`・`timeout`）と、`lister: (raw) => AdminsLister`（読み取りを権限チェック層で包む）。url・region はハンドラが渡す |
+| `alertsCollection`    | 生のコレクション              | `(raw) => AlertsCollection`。alerts の書き込みを自分の層で包むアプリが使う                                                                                                                              |
+| `recordHttpTimeoutMs` | 2500                          | alerts の書き込みの HTTP の時間切れ                                                                                                                                                                     |
+| `log`                 | `logJson`                     | 設定の誤りの警告（`ALERTS_SKIP_LOG_GROUPS_EMPTY`）の出力先                                                                                                                                              |
+| `notify`              | 上の既定                      | `createNotifyHandler` に渡す設定（`windows`・`rate`・`adminCacheSec`・`failOnAnyChannelError`・`now`・`logger`・`skipRecordEvents`・`recordLimits`・`recordBreaker`）                                   |
+| `overrides`           | なし                          | テスト用の差し替え（`store`・`channels`・`admins`・`alertsCollection`・`ssmClient`・`emailSender`）                                                                                                     |
+
+アプリごとの書き方（現行の挙動を再現する）:
+
+```ts
+// asanowa: 既定のまま（管理者は id、生のコレクション）
+export const handler = createOpsNotifyHandler();
+
+// astro: 管理者は email ?? id・id の昇順で、読み取りを権限チェック層に通す
+export const handler = createOpsNotifyHandler({
+  admins: {
+    recipientFields: ['email', 'id'],
+    sortById: true,
+    lister: (raw) => authorizedCollection(ADMINS, raw, PERMISSION_MATRIX, { role: 'system' }),
+  },
+});
+```
+
+アプリに残るもの: エントリの数行（と、権限チェック層を通すアプリの包み方）、バンドルの作成、`terraform/ops-notify` の module ブロック。IAM は `terraform/ops-notify` が付けるもの（notices の UpdateItem、Records の IAM URL、SSM の GetParameter、SES の送信）で足りる。
+
 ## 配線の注意（各アプリ）
 
 - **通知ハンドラのロググループは購読しない**（自分のログで無限ループになる）。失敗は Lambda の失敗先（SNS など）→ 固定の運用者のアドレスへ届ける
@@ -177,7 +228,7 @@ export const handler = createNotifyHandler({
 - 環境変数: 既存の `NOTICE_TABLE` / `RECORDS_IAM_URL` に加えて、`ADMIN_BASE_URL`（任意。無ければ URL を載せない）
 - IAM: 通知ストアへは `dynamodb:UpdateItem` だけ（既存の権限のまま。`GetItem` は要らない）。Records の IAM URL の呼び出し（`lambda:InvokeFunctionUrl`）は、管理者の一覧の取得で既に持っている
 - 同時実行数: 同じレコードへの同時の書き込みはシャドーを孤立させうるので、**記録を有効にするときだけ**、通知 Lambda の予約同時実行数を 1 にする（今の通知 Lambda は未設定。入れると、記録なしでも遅れ方が変わる）。直列化は努力目標で、強制はされない（打ち切った HTTP は止まらない・削除の定時処理と重なる・管理画面から書ける）。孤立したシャドーは `src/scripts/repair-shadows.ts` で修復できる
-- ライブラリは Terraform を提供しない（`alerts` の定時削除・同時実行数・環境変数は各アプリの infra で）
+- Terraform は `terraform/ops-notify`・`terraform/alerts-cleanup`（1.21.0。[README](../terraform/ops-notify/README.md)）。Lambda の成果物（エントリ）と、秘密の置き場は各アプリ
 
 ### 削除（定時 Lambda）
 

package/docs/SYSTEM_CHANGES.md

@@ -183,4 +183,4 @@ ADR 0006 の段階 2 の手順: astro で先に置き換えて dev で確認し
 - Slack の文言は asanowa に揃えた。astro の「記録を省いた Lambda」は「ほかに記録しきれなかった Lambda」になる
 - Slack の送信は `postSlackText` を通る: webhook の URL が `https://hooks.slack.com/` で始まらないと送らない（`slack.urlPrefix`）。失敗の warn の理由は従来と同じ `HTTP 500` やエラー名（時間切れは `AbortError` ではなく `TimeoutError`）
 - asanowa の `changeId` の読み取りは `findOne`（404 を null にする）から `find({ id }, { sort: { id: 'asc' }, limit: 1 })`（Records の ID の経路。PK/SK の Query 1 回） に変わる。Records の ITEM_NOT_FOUND の warn が出なくなる
-- 記録 Lambda の Terraform（`source_file`）は、アプリのバンドルのまま（Terraform のモジュール化は段階 6）
+- 記録 Lambda の Terraform は `terraform/system-change-recorder`（1.21.0。段階 6。[README](../terraform/system-change-recorder/README.md)）。成果物はアプリのバンドルのまま（`source_file` で渡す）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exabugs/dynamodb-client",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "DynamoDB Single-Table Client SDK with MongoDB-like API, Shadow Records, and Lambda implementation for serverless applications",
   "author": "exabugs",
   "license": "MIT",
@@ -127,6 +127,10 @@
       "import": "./dist/notify/index.js",
       "types": "./dist/notify/index.d.ts"
     },
+    "./notify/ops": {
+      "import": "./dist/notify/ops/index.js",
+      "types": "./dist/notify/ops/index.d.ts"
+    },
     "./system-changes": {
       "import": "./dist/system-changes/index.js",
       "types": "./dist/system-changes/index.d.ts"
@@ -173,6 +177,7 @@
     "@aws-crypto/sha256-js": "5.2.0",
     "@aws-sdk/client-dynamodb": "3.946.0",
     "@aws-sdk/client-s3": "3.946.0",
+    "@aws-sdk/client-sesv2": "3.946.0",
     "@aws-sdk/client-ssm": "3.946.0",
     "@aws-sdk/cloudfront-signer": "3.946.0",
     "@aws-sdk/credential-provider-node": "3.946.0",

package/terraform/README.md

@@ -219,6 +219,15 @@ make logs-records ENV=dev
 aws logs tail /aws/lambda/my-project-dev-records --follow
 ```
 
+## 運用のモジュール（1.21.0）
+
+Records のクライアントとして動く運用の Lambda を、別のモジュールとして持つ（ADR 0006 の (b)）。Lambda の成果物（エントリ）はアプリが作り、`source_file` で渡す。
+
+- [ops-notify](ops-notify/README.md): 運用通知（ログ・アラーム・生存確認 → Slack とメール。alerts の記録）
+- [alerts-cleanup](alerts-cleanup/README.md): alerts の定時削除
+- [system-change-recorder](system-change-recorder/README.md): システム変更履歴の記録
+- [media](media/README.md): メディア（アップロード・処理・配信）
+
 ## 関連ドキュメント
 
 - [パッケージREADME](../README.md) - クライアントライブラリの使用方法

package/terraform/alerts-cleanup/README.md

@@ -0,0 +1,65 @@
+# alerts の定時削除 Lambda Terraformモジュール
+
+ADR 0006 の (b)（1.21.0）。asanowa・astro の `infra/modules/alerts-cleanup` を 1 つにしたもの。使い方の詳細は [docs/NOTIFY.md](../../docs/NOTIFY.md) の「削除（定時 Lambda）」。
+
+## 作るもの
+
+- Lambda `<project>-<env>-alerts-cleanup`（Node.js 22、arm64、120 秒、256 MB。構造化ログ JSON）と、そのロググループ・実行ロール
+- EventBridge の定時ルール（既定 毎日 03:00 JST）とターゲット（再試行 0）、呼び出しの許可
+- 権限: Records の IAM 版 URL の呼び出しだけ。DynamoDB には直接触れない
+- 環境変数: `PROJECT_NAME`（`createAlertsCleanupHandler` の `app` の既定）、`RECORDS_IAM_URL`
+
+## 前提
+
+- 参照は `node_modules` のパス（版は npm の版で固定される。git の `ref` ではない）。例: アプリの infra が `infra/` なら `source = "../node_modules/@exabugs/dynamodb-client/terraform/alerts-cleanup"`、`infra/apps/<app>/` なら `"../../../node_modules/..."`
+- **Lambda の成果物はアプリが作り、`source_file`（バンドル済みの 1 ファイル）と `handler` で渡す**。エントリはアプリの数行（`createAlertsCleanupHandler`。アプリ名や、権限チェック層を通すアプリの包み方を渡す）なので、ライブラリの dist は使わない
+- zip は `${path.root}/.terraform/archives/alerts-cleanup.zip` に作る（`path.module` を使わない。pnpm の版つきのパスが state に入ると、版を上げるたびに差分が出るため）
+- pnpm では、版を上げた後に `.terraform/modules` を消してから `terraform init` する（[../README.md](../README.md) の注意）
+- モジュール全体の `depends_on` は使わない（依存先に変更があると、中のデータソースが apply 時の読み取りになり、既存のリソースが作り直しになる）。依存は、出力の値（`log_group_name` など）で渡す
+
+## 使い方
+
+```hcl
+module "alerts_cleanup" {
+  source = "../node_modules/@exabugs/dynamodb-client/terraform/alerts-cleanup"
+
+  project_name             = var.project_name
+  environment              = var.environment
+  records_iam_function_url = module.records.iam_function_url
+  records_iam_alias_arn    = module.records.iam_alias_arn
+  log_retention_days       = var.log_retention_days
+
+  source_file = "${path.root}/../apps/server/dist/alerts-cleanup.cjs"
+  handler     = "alerts-cleanup.handler"
+}
+```
+
+## 変数
+
+| 変数                                                 | 既定                 | 説明                                                    |
+| ---------------------------------------------------- | -------------------- | ------------------------------------------------------- |
+| `project_name` / `environment`                       | 必須                 | 名前の接頭辞 `<project>-<env>`。環境変数 `PROJECT_NAME` |
+| `records_iam_function_url` / `records_iam_alias_arn` | 必須                 | Records の IAM 版 Function URL と、そのエイリアスの ARN |
+| `source_file` / `handler`                            | 必須                 | アプリのバンドル（1 ファイル）と、ハンドラ              |
+| `schedule_expression`                                | `cron(0 18 * * ? *)` | 実行間隔（毎日 03:00 JST）                              |
+| `log_retention_days`                                 | 7                    | ロググループの保持日数                                  |
+
+## 出力
+
+`function_name`、`function_arn`、`log_group_name`（ops-notify に購読させる）
+
+## アプリに残るもの
+
+- 上の module ブロック（`source`・`source_file`・`handler` と設定の値）
+- Lambda のエントリ（`createAlertsCleanupHandler` を呼ぶ数行）とバンドルの作成（esbuild など）
+- 秘密（webhook の URL など）の SSM パラメータの作成
+
+## アプリのモジュールからの移行（置き換えを起こさない）
+
+リソースのアドレス・名前は、asanowa / astro の旧モジュール（`infra/modules/alerts-cleanup`）と同じ。**module ブロックの名前（`module "alerts_cleanup"`）を変えずに `source` だけを差し替え**、`source_file`・`handler` を足す。アドレスが変わらないので `moved` は要らない（ラッパーのモジュールで包むと、アドレスが変わり `moved` が要る）。
+
+1. `terraform init`（モジュールの取り直し）→ `terraform plan`
+2. **0 to add / 0 to destroy、`must be replaced` が無い**ことを確かめる。出てよいのは in-place の更新だけ（文言の差。astro ではルールの description が英語の文言に、Lambda に `PROJECT_NAME` が加わる）
+3. 確認のうえ apply。旧モジュールのディレクトリを消す
+
+詳細と実機の確認は [ADR 0006](../../docs/adr/0006-library-owns-table-operations.md) の段階 6。

package/terraform/alerts-cleanup/main.tf

@@ -0,0 +1,111 @@
+# 運用通知の記録（alerts）の定時削除（ADR 0003・ADR 0006 の (b)。docs/NOTIFY.md の「削除（定時 Lambda）」）
+# 最後の発生から 28 日を過ぎた alerts を、定時に消す（ネイティブ TTL は効かない）。
+# Lambda の成果物はアプリが作り、source_file で渡す（実装は `createAlertsCleanupHandler`）。
+#
+# 失敗は構造化ログ（error）に出す。このロググループは、通知（../ops-notify）に購読させる。
+# リソースのアドレス・名前は、asanowa / astro の旧モジュール（infra/modules/alerts-cleanup）と同じ。
+
+locals {
+  prefix = "${var.project_name}-${var.environment}"
+}
+
+data "archive_file" "cleanup" {
+  type        = "zip"
+  source_file = var.source_file
+  output_path = "${path.root}/.terraform/archives/alerts-cleanup.zip"
+}
+
+resource "aws_cloudwatch_log_group" "cleanup" {
+  name              = "/aws/lambda/${local.prefix}-alerts-cleanup"
+  retention_in_days = var.log_retention_days
+}
+
+resource "aws_iam_role" "cleanup" {
+  name = "${local.prefix}-alerts-cleanup-role"
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Action    = "sts:AssumeRole"
+      Effect    = "Allow"
+      Principal = { Service = "lambda.amazonaws.com" }
+    }]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "cleanup_logs" {
+  role       = aws_iam_role.cleanup.name
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
+}
+
+# Records Lambda の IAM 認証版 URL（エイリアス）を呼ぶ権限だけ（最小権限）。DynamoDB には直接触れない
+resource "aws_iam_role_policy" "cleanup_invoke_records" {
+  name = "${local.prefix}-alerts-cleanup-invoke-records"
+  role = aws_iam_role.cleanup.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = ["lambda:InvokeFunctionUrl"]
+      Resource = [var.records_iam_alias_arn]
+    }]
+  })
+}
+
+resource "aws_lambda_function" "cleanup" {
+  function_name    = "${local.prefix}-alerts-cleanup"
+  role             = aws_iam_role.cleanup.arn
+  filename         = data.archive_file.cleanup.output_path
+  source_code_hash = data.archive_file.cleanup.output_base64sha256
+  handler          = var.handler
+  runtime          = "nodejs22.x"
+  architectures    = ["arm64"]
+  timeout          = 120
+  memory_size      = 256
+
+  environment {
+    # PROJECT_NAME は createAlertsCleanupHandler の app の既定（app を渡すアプリは読まない）
+    variables = {
+      PROJECT_NAME    = var.project_name
+      RECORDS_IAM_URL = var.records_iam_function_url
+    }
+  }
+
+  logging_config {
+    log_format = "JSON"
+    log_group  = aws_cloudwatch_log_group.cleanup.name
+  }
+
+  depends_on = [aws_iam_role_policy_attachment.cleanup_logs]
+}
+
+# 再試行は 0（翌日の定時実行で残りを消す。失敗はログ → 通知で知る）
+resource "aws_lambda_function_event_invoke_config" "cleanup" {
+  function_name          = aws_lambda_function.cleanup.function_name
+  maximum_retry_attempts = 0
+}
+
+resource "aws_cloudwatch_event_rule" "cleanup" {
+  name                = "${local.prefix}-alerts-cleanup"
+  description         = "Delete ops alerts records older than 28 days (daily 03:00 JST)"
+  schedule_expression = var.schedule_expression
+}
+
+resource "aws_cloudwatch_event_target" "cleanup" {
+  rule = aws_cloudwatch_event_rule.cleanup.name
+  arn  = aws_lambda_function.cleanup.arn
+
+  retry_policy {
+    maximum_retry_attempts       = 0
+    maximum_event_age_in_seconds = 3600
+  }
+}
+
+resource "aws_lambda_permission" "cleanup_events" {
+  statement_id  = "AllowEventBridgeInvoke"
+  action        = "lambda:InvokeFunction"
+  function_name = aws_lambda_function.cleanup.function_name
+  principal     = "events.amazonaws.com"
+  source_arn    = aws_cloudwatch_event_rule.cleanup.arn
+}

package/terraform/alerts-cleanup/outputs.tf

@@ -0,0 +1,14 @@
+output "function_name" {
+  description = "alerts の定時削除 Lambda の関数名"
+  value       = aws_lambda_function.cleanup.function_name
+}
+
+output "log_group_name" {
+  description = "alerts の定時削除 Lambda のロググループ名（通知 Lambda が購読する）"
+  value       = aws_cloudwatch_log_group.cleanup.name
+}
+
+output "function_arn" {
+  description = "alerts の定時削除 Lambda の ARN"
+  value       = aws_lambda_function.cleanup.arn
+}

package/terraform/alerts-cleanup/variables.tf

@@ -0,0 +1,42 @@
+variable "project_name" {
+  description = "プロジェクト名"
+  type        = string
+}
+
+variable "environment" {
+  description = "環境識別子（dev, prd）"
+  type        = string
+}
+
+variable "records_iam_function_url" {
+  description = "Records Lambda の AWS_IAM 認証版 Function URL（alerts を読み、消す）"
+  type        = string
+}
+
+variable "records_iam_alias_arn" {
+  description = "Records Lambda の IAM 認証用エイリアスの ARN（lambda:InvokeFunctionUrl の Resource）"
+  type        = string
+}
+
+variable "schedule_expression" {
+  description = "実行間隔（既定: 毎日 03:00 JST = 18:00 UTC）"
+  type        = string
+  default     = "cron(0 18 * * ? *)"
+}
+
+variable "log_retention_days" {
+  description = "CloudWatch Logsの保持期間（日数）"
+  type        = number
+  default     = 7
+}
+
+variable "source_file" {
+  description = "Lambda の成果物（バンドル済みの 1 ファイル。例: apps/server/dist/alerts-cleanup.cjs）。zip にして使う"
+  type        = string
+}
+
+variable "handler" {
+  description = "Lambda のハンドラ（例: alerts-cleanup.handler）"
+  type        = string
+}
+

package/terraform/alerts-cleanup/versions.tf

@@ -0,0 +1,16 @@
+# provider の版: astro（5.x）と asanowa（6.x）の両方で使う。
+# 下限は Lambda の logging_config（5.x の途中で追加）。上限は data.aws_region の name（6.x で非推奨）が消える 7.x の前まで
+terraform {
+  required_version = ">= 1.5"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = ">= 5.30, < 7.0"
+    }
+    archive = {
+      source  = "hashicorp/archive"
+      version = ">= 2.0"
+    }
+  }
+}

package/terraform/ops-notify/README.md

@@ -0,0 +1,109 @@
+# 運用通知 Terraformモジュール
+
+ADR 0006 の (b)（1.21.0）。asanowa・astro の `infra/modules/ops-notify` を 1 つにしたもの。使い方の詳細は [docs/NOTIFY.md](../../docs/NOTIFY.md)。
+
+## 作るもの
+
+- 通知 Lambda `<project>-<env>-notify`（Node.js 22、arm64、60 秒、256 MB。構造化ログ JSON）と、そのロググループ・実行ロール
+- 重複抑制・流量制限の記録のテーブル `<project>-<env>-notices`（pk、TTL `ttl`。Records の本体テーブルではない内部用）
+- 失敗先の SNS トピック `<project>-<env>-notify-failure`（運用者のメールの購読つき）。非同期の再試行 0
+- 入口 1: `watched_log_group_names` のロググループの購読（広めの語句。通知するかはハンドラが判定する）
+- 入口 2: CloudWatch アラームの状態変化（名前が `<project>-<env>-` で始まるもの）
+- 入口 3: 生存確認（既定 週 1 回）
+- us-east-1 のアラーム（CloudFront など）の転送（`forward_us_east_1_alarms = true` のときだけ）: us-east-1 の EventBridge ルールと、ホームのリージョンの default バスへ送るロール。転送されたイベントは入口 2 のルールが拾う
+- 権限: notices の `UpdateItem`、Records の IAM 版 URL の呼び出し、webhook のパラメータの読み取り、失敗先の SNS、SES（`mail_from` があるときだけ。送信元アドレスとドメインに絞る）
+
+## 前提
+
+- 参照は `node_modules` のパス（版は npm の版で固定される。git の `ref` ではない）。例: アプリの infra が `infra/` なら `source = "../node_modules/@exabugs/dynamodb-client/terraform/ops-notify"`、`infra/apps/<app>/` なら `"../../../node_modules/..."`
+- **Lambda の成果物はアプリが作り、`source_file`（バンドル済みの 1 ファイル）と `handler` で渡す**。エントリはアプリの数行（1.22.0 からは `@exabugs/dynamodb-client/notify/ops` の `createOpsNotifyHandler()`。権限チェック層を通すアプリは包み方を渡す。[docs/NOTIFY.md](../../docs/NOTIFY.md) の「通知 Lambda のエントリ」）なので、ライブラリの dist は使わない
+- zip は `${path.root}/.terraform/archives/notify.zip` に作る（`path.module` を使わない。pnpm の版つきのパスが state に入ると、版を上げるたびに差分が出るため）
+- pnpm では、版を上げた後に `.terraform/modules` を消してから `terraform init` する（[../README.md](../README.md) の注意）
+- モジュール全体の `depends_on` は使わない（依存先に変更があると、中のデータソースが apply 時の読み取りになり、既存のリソースが作り直しになる）。依存は、出力の値（`log_group_name` など）で渡す
+
+## 使い方
+
+```hcl
+module "ops_notify" {
+  source = "../node_modules/@exabugs/dynamodb-client/terraform/ops-notify"
+
+  # 必須（forward_us_east_1_alarms が false でも）。モジュールが aws.us_east_1 の別名を宣言しているため
+  providers = {
+    aws.us_east_1 = aws.us_east_1
+  }
+
+  project_name             = var.project_name
+  environment              = var.environment
+  records_iam_function_url = module.records.iam_function_url
+  records_iam_alias_arn    = module.records.iam_alias_arn
+  log_retention_days       = var.log_retention_days
+
+  source_file = "${path.root}/../apps/server/dist/notify.cjs"
+  handler     = "notify.handler"
+
+  # 通知 Lambda 自身のロググループは入れない（無限ループ）
+  watched_log_group_names = [
+    module.records.log_group_name,
+    module.alerts_cleanup.log_group_name,
+    module.system_change_recorder.log_group_name,
+  ]
+  slack_webhook_param_name = "/${var.project_name}/${var.environment}/ops/slack-webhook"
+  mail_from                = var.ops_mail_from
+  ses_identity_domain      = var.ops_ses_identity_domain
+  operator_email           = var.ops_operator_email
+
+  # alerts（通知を管理画面のレコードとして残す）。空なら記録しない
+  admin_base_url                 = var.ops_admin_base_url
+  skip_record_log_groups         = [module.records.log_group_name]
+  reserved_concurrent_executions = var.ops_admin_base_url == "" ? null : 1
+}
+```
+
+## provider
+
+`aws`（ホームのリージョン）に加えて、**別名 `aws.us_east_1` を `providers` で必ず渡す**（`configuration_aliases`。転送を使わないときも要る。リージョンは us-east-1）。呼び出し側に無ければ、次を足す。
+
+```hcl
+provider "aws" {
+  alias  = "us_east_1"
+  region = "us-east-1"
+}
+```
+
+## 変数
+
+| 変数                                                 | 既定                      | 説明                                                                                                            |
+| ---------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `project_name` / `environment`                       | 必須                      | 名前の接頭辞 `<project>-<env>`。環境変数 `PROJECT_NAME` / `ENV_NAME`                                            |
+| `records_iam_function_url` / `records_iam_alias_arn` | 必須                      | Records の IAM 版 Function URL（管理者の一覧を読み、alerts を書く）と、そのエイリアスの ARN                     |
+| `source_file` / `handler`                            | 必須                      | アプリのバンドル（1 ファイル）と、ハンドラ                                                                      |
+| `watched_log_group_names`                            | 必須                      | 購読するロググループ。通知 Lambda 自身のものは入れない                                                          |
+| `slack_webhook_param_name`                           | 必須                      | Slack の webhook の SSM パラメータ名（SecureString。値は Terraform で扱わない）                                 |
+| `operator_email`                                     | 必須                      | 通知 Lambda 自身の失敗の届け先（SNS の確認メールが届く）                                                        |
+| `mail_from` / `ses_region` / `ses_identity_domain`   | `""` / `us-east-1` / `""` | メールの送信元と SES。`mail_from` が空ならメールは送らない                                                      |
+| `heartbeat_schedule`                                 | `rate(7 days)`            | 生存確認の間隔                                                                                                  |
+| `log_retention_days`                                 | 7                         | ロググループの保持日数                                                                                          |
+| `admin_base_url`                                     | `""`                      | 管理画面のベース URL。空でなければ alerts に記録し、通知に詳細の URL を載せる。空なら環境変数に入れない         |
+| `skip_record_log_groups`                             | `[]`                      | alerts に記録しないロググループ。**Records のロググループを必ず入れる**（ループ防止）。空なら環境変数に入れない |
+| `forward_us_east_1_alarms`                           | `false`                   | us-east-1 のアラームの状態変化を、ホームのリージョンの default バスへ転送する                                   |
+| `reserved_concurrent_executions`                     | `null`                    | 予約同時実行数。alerts の記録を有効にするときだけ 1                                                             |
+
+## 出力
+
+`function_name`、`function_arn`、`failure_topic_arn`、`notice_table_name`
+
+## アプリに残るもの
+
+- 上の module ブロック（`source`・`providers`・`source_file`・`handler` と設定の値）
+- Lambda のエントリ（`createOpsNotifyHandler` を export する数行）とバンドルの作成（esbuild など）
+- 秘密（webhook の URL など）の SSM パラメータの作成
+
+## アプリのモジュールからの移行（置き換えを起こさない）
+
+リソースのアドレス・名前は、asanowa / astro の旧モジュール（`infra/modules/ops-notify`）と同じ。**module ブロックの名前（`module "ops_notify"`）を変えずに `source` だけを差し替え**、`source_file`・`handler` を足す。アドレスが変わらないので `moved` は要らない（ラッパーのモジュールで包むと、アドレスが変わり `moved` が要る）。
+
+1. `terraform init`（モジュールの取り直し）→ `terraform plan`
+2. **0 to add / 0 to destroy、`must be replaced` が無い**ことを確かめる。出てよいのは in-place の更新だけ（asanowa では zip の名前〔`ops-notify.zip` → `notify.zip`〕の `filename` が変わる。中身・`source_code_hash` は同じ。astro では環境変数 `PROJECT_NAME` が加わる）
+3. 確認のうえ apply。旧モジュールのディレクトリを消す
+
+詳細と実機の確認は [ADR 0006](../../docs/adr/0006-library-owns-table-operations.md) の段階 6。