ampless 1.0.0-alpha.33 → 1.0.0-alpha.35

package/dist/index.js

@@ -224,6 +224,14 @@ function definePlugin(p) {
       );
     }
   }
+  if (p.trust_level === "privileged") {
+    const hasHooks = p.hooks && Object.keys(p.hooks).length > 0 || (p.capabilities?.includes("eventHooks") ?? false);
+    if (hasHooks) {
+      console.warn(
+        `[ampless] Plugin "${p.name}" declares trust_level: 'privileged' with event hooks, but no privileged Lambda is provisioned yet. Hooks will not execute. Sync render surfaces (publicHead / metadata / publicBodyForPost / etc.) work normally regardless of trust_level. See docs/architecture/08-plugin-architecture.md#trust-levels for the future plan.`
+      );
+    }
+  }
   return p;
 }
 

package/docs/plugin-author-guide.ja.md

@@ -279,11 +279,20 @@ runtime がチェックする内容:
 
 3 階層、選択基準は **イベントフック (hooks) が何を必要とするか** で決まります (sync サーフェスは IAM に触れない):
 
-| 階層 | IAM | 用途 |
-|---|---|---|
-| `untrusted` | なし (SQS consume のみ) | head/body descriptor、webhook 配送、コンテンツ変換 |
-| `trusted` | 投稿読み出し、`public/plugins/<instanceId ?? name>/...` への書き込み | RSS フィード、sitemap、計算済み JSON インデックス |
-| `privileged` | 予約 | 将来: SES、secret、private S3 |
+| 階層 | IAM | 今日動くもの | 用途 |
+|---|---|---|---|
+| `untrusted` | なし (SQS consume のみ) | 同期サーフェス + イベントフック | head/body descriptor、webhook 配送、コンテンツ変換 |
+| `trusted` | 投稿読み出し、`public/plugins/<instanceId ?? name>/...` への書き込み | 同期サーフェス + イベントフック | RSS フィード、sitemap、計算済み JSON インデックス |
+| `privileged` | 予約 | 同期サーフェスのみ — イベントフックはサイレントフィルタ（警告ログあり） | 将来: SES、secret、private S3 |
+
+> **`privileged` プラグイン作者へ：** `trust_level: 'privileged'` とイベント
+> `hooks` を宣言した場合、**現時点でフックは実行されません**。両 processor が
+> privileged プラグインをフィルタアウトし、一致する SQS イベントごとに
+> `console.warn` を出力するため、サイレントドロップは可視化されます。
+> 同期サーフェス（`publicHead`、`publicBodyEnd`、`metadata`、`publicBodyForPost`、
+> `publicHtmlForPost`）は `trust_level` に関わらず正常に動き、警告も出ません。
+> privileged Lambda が用意された際、`'privileged'` を宣言済みのプラグインは
+> 自動的に新しい tier を使えるようになります — コードの変更は不要です。
 
 決め方の目安:
 
@@ -291,7 +300,7 @@ runtime がチェックする内容:
 - **hooks から投稿を読みたい (publish 時にフィードを再生成等)** → `trusted`
 - **`public/plugins/*` 以外への S3 PutObject や他の AWS API が必要** → 今はプラグインで ship せず、privileged 層を待つかプラグイン外で実装
 
-trust level がズレているプラグインは「権限不足で sliently fail」または「不要に強い権限を持つ」のどちらか。階層を切り替えて再デプロイすれば直ります。
+trust level がズレているプラグインは「権限不足でサイレントに fail」または「不要に強い権限を持つ」のどちらか。階層を切り替えて再デプロイすれば直ります。
 
 ---
 
@@ -563,6 +572,50 @@ React 19 はさらに、クライアントコンポーネントのレンダー
 
 投稿単位の見える出力には `publicHtmlForPost` を使ってください（Phase 6d — 上の例と §6 の `PublicPostHtmlDescriptor` 参照）。runtime が post 本文の周囲の固定スロットにサーバーサイド HTML を出すので、hydration と競合しません。
 
+---
+
+## 6a. 予約投稿とコンテンツイベント
+
+ampless は**予約投稿**をサポートしています。`status: 'published'` かつ `publishedAt` が未来の投稿は、その時刻まで公開読み出しから隠されます。`publishedAt` を過ぎると、サイトの自然なキャッシュ有効期限（デフォルト ≤ ~5 分）の範囲内で公開されます — 秒単位の正確なトリガーはありません。
+
+### イベントは保存時に発火する（`publishedAt` のタイミングではない）
+
+`content.published`（および `content.updated`）は DynamoDB Streams 経由で**投稿が保存されたとき**に emit されます。`publishedAt` が到来したときではありません。つまり、`content.published` に反応するプラグインは、投稿が未来日時の場合、**その投稿が公開される前**に実行されます。
+
+現在の投稿一覧から公開アセットを再構築する trusted プラグイン（RSS、sitemap、JSON インデックスなど）にとってはこれは問題ありません — `listPublishedPosts()` が未来日時の投稿をすでに除外しているため、再生成されたアセットはその投稿が公開されるまでリストに含まれません。
+
+一方、**外部通知プラグイン**（webhook、プッシュ通知、SNS 投稿など）には影響があります。投稿の URL が 404 を返しているまたはホームページにリダイレクトされている間に通知が配信されてしまいます。
+
+### 推奨パターン: `publishedAt` でゲートする
+
+ディスパッチの前に `event.payload.publishedAt` を確認します。投稿が未来日時の場合はスキップまたは保留します:
+
+```ts
+hooks: {
+  async 'content.published'(event, ctx) {
+    const { publishedAt } = event.payload
+
+    // 予約投稿には通知を送らない。イベントは保存時に発火するが、
+    // 投稿が公開されるのは publishedAt になってから。
+    if (publishedAt && new Date(publishedAt) > new Date()) {
+      return
+    }
+
+    // 投稿は今すぐ公開状態 — 通知しても安全。
+    await sendWebhook(event.payload, ctx)
+  },
+}
+```
+
+イベントペイロード内の `publishedAt` は UTC ISO 8601 文字列（`...Z`）です。`Date.now()` と比較する前に `new Date()` またはお好みの日付ライブラリでパースしてください。
+
+### 今後の対応
+
+`content.published` の発火を保存時ではなく `publishedAt` のタイミングに合わせる機能 — EventBridge Scheduler または DynamoDB TTL トリガー Lambda によるスケジューラーコンポーネントが必要 — は計画中の機能強化です。現リリースのスコープには含まれていません。それまでの間は上記のパターンが通知プラグインにおける推奨ガードです。
+
+オペレーター視点からの `publishedAt` セマンティクスの全体像は [`docs/scheduled-publishing.md`](https://github.com/heavymoons/ampless/blob/main/docs/scheduled-publishing.ja.md) を参照してください。
+
+---
 
 ### CSP nonce（Phase 1 予約）
 

package/docs/plugin-author-guide.md

@@ -341,11 +341,22 @@ Three tiers, picked by what the plugin needs to do **inside
 event hooks** (the sync surfaces — metadata, head, body — don't
 touch IAM):
 
-| Tier | IAM | Used by |
-|---|---|---|
-| `untrusted` | none (SQS consume only) | head/body descriptors, webhook delivery, content transforms |
-| `trusted` | read posts, write `public/plugins/<instanceId ?? name>/...` | RSS feed, sitemap, computed JSON indexes |
-| `privileged` | reserved | future: SES, secrets, private S3 |
+| Tier | IAM | What runs today | Used by |
+|---|---|---|---|
+| `untrusted` | none (SQS consume only) | sync surfaces + event hooks | head/body descriptors, webhook delivery, content transforms |
+| `trusted` | read posts, write `public/plugins/<instanceId ?? name>/...` | sync surfaces + event hooks | RSS feed, sitemap, computed JSON indexes |
+| `privileged` | reserved | sync surfaces only — event hooks are silently filtered out (warning logged) | future: SES, secrets, private S3 |
+
+> **Warning for `privileged` plugin authors:** If you declare
+> `trust_level: 'privileged'` with event `hooks` today, **your hooks
+> WILL NOT EXECUTE**. Both event processors filter out privileged
+> plugins and emit a `console.warn` on every matching SQS event so
+> the drop is visible. Sync render surfaces (`publicHead`,
+> `publicBodyEnd`, `metadata`, `publicBodyForPost`, `publicHtmlForPost`)
+> work normally regardless of `trust_level` and emit no warning.
+> When the privileged Lambda provisioning PR lands, plugins that
+> already declared `'privileged'` will automatically pick up the new
+> tier — nothing needs to change in your code.
 
 Rule of thumb:
 
@@ -719,6 +730,72 @@ the example above and §6's `PublicPostHtmlDescriptor`). The runtime
 emits server-side HTML at fixed slots around the post body, so
 nothing races against hydration.
 
+---
+
+## 6a. Scheduled posts and content events
+
+ampless supports **scheduled publishing**: a post with `status:
+'published'` and a future `publishedAt` is hidden from all public
+reads until that time. Once `publishedAt` arrives, the post becomes
+visible within the site's natural cache window (≤ ~5 minutes by
+default) — there is no exact-time trigger.
+
+### Events fire at save time, not at `publishedAt`
+
+`content.published` (and `content.updated`) are emitted via DynamoDB
+Streams **when the post is saved**, not when `publishedAt` arrives.
+This means a plugin that reacts to `content.published` will run
+**before the post is publicly visible** when the post is future-dated.
+
+For trusted plugins that rebuild public assets from the current post
+list (RSS, sitemap, JSON indexes), this is harmless — `listPublishedPosts()`
+already filters out future-dated posts, so the regenerated asset
+simply omits the scheduled post until it goes live.
+
+For **outbound-notification plugins** (webhook, push notification,
+social post) the early fire matters: the notification will be
+delivered to subscribers while the post URL still returns 404 or
+redirects to the home page.
+
+### Recommended pattern: gate on `publishedAt`
+
+Check `event.payload.publishedAt` before dispatching. Skip or defer
+when the post is future-dated:
+
+```ts
+hooks: {
+  async 'content.published'(event, ctx) {
+    const { publishedAt } = event.payload
+
+    // Skip notification for future-scheduled posts. The event fires
+    // at save time, but the post won't be public until publishedAt.
+    if (publishedAt && new Date(publishedAt) > new Date()) {
+      return
+    }
+
+    // Post is live now — safe to notify.
+    await sendWebhook(event.payload, ctx)
+  },
+}
+```
+
+The `publishedAt` value in the event payload is a UTC ISO 8601 string
+(`...Z`). Parse it with `new Date()` or your preferred date library
+before comparing against `Date.now()`.
+
+### Future work
+
+Aligning event emission with the scheduled time — so `content.published`
+fires at `publishedAt` rather than at save time — is a planned
+enhancement. It requires a scheduler component (EventBridge Scheduler
+or a DynamoDB TTL-triggered Lambda) and is not yet in scope for the
+current release. Until then, the pattern above is the recommended
+guard for notification plugins.
+
+For a full description of `publishedAt` semantics from the operator's
+perspective, see [`docs/scheduled-publishing.md`](https://github.com/heavymoons/ampless/blob/main/docs/scheduled-publishing.md).
+
+---
 
 ### CSP nonce (Phase 1 reservation)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ampless",
-  "version": "1.0.0-alpha.33",
+  "version": "1.0.0-alpha.35",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",