ampless 1.0.0-alpha.35 → 1.0.0-alpha.37

package/dist/index.d.ts

@@ -633,6 +633,28 @@ interface PluginRuntimeContext {
      */
     writePublicAsset(key: string, body: string | Uint8Array, contentType: string): Promise<string>;
 }
+/**
+ * Context passed to the `uninstall` lifecycle hook (Phase 1
+ * reservation: runtime no-op — see `AmplessPlugin.uninstall`).
+ *
+ * Phase 1: structurally identical to `PluginRuntimeContext`. The
+ * dedicated type exists so future cleanup helpers
+ * (`deletePublicAsset`, `deletePluginSetting`, `deletePluginSecret`)
+ * can be added here without exposing them to regular event hooks,
+ * which take `PluginRuntimeContext` and should not be able to
+ * delete state from arbitrary plugin areas.
+ *
+ * Phase 1 scope is limited to: (a) reserving the type name, (b)
+ * reserving the hook signature `(ctx: PluginUninstallContext) =>
+ * Promise<void>`. Cleanup helper methods are NOT included in
+ * Phase 1 — plugin authors writing `await ctx.deletePublicAsset(...)`
+ * today would hit a TS error. The actual cleanup body lands when
+ * the future lifecycle-dispatch PR adds the helper methods to this
+ * type (additive, no breaking change for plugins that declared an
+ * empty `uninstall` body in advance).
+ */
+interface PluginUninstallContext extends PluginRuntimeContext {
+}
 /**
  * Extended runtime context for **trusted** hook handlers. Adds
  * `secret<T>(key)` — an async accessor that reads from the isolated
@@ -874,6 +896,80 @@ interface PluginSettingsManifest {
      * capability warns.
      */
     secret?: readonly PluginSecretField[];
+    /**
+     * Optional manifest shape version (Phase 1 reservation: runtime
+     * no-op).
+     *
+     * Plugin authors bump this integer when they change the shape of
+     * `public` or `secret` field arrays in a way that today's
+     * write/read paths cannot transparently absorb — i.e. when a field
+     * is renamed, when a field's `type` changes incompatibly, or when
+     * a field's semantic meaning shifts (same key + same type but the
+     * value should be re-interpreted).
+     *
+     * **Phase 1 scope**: the field is type-only. The runtime does NOT
+     * read it today, does NOT persist it next to stored values, and
+     * does NOT trigger any migration. Today's behaviour around shape
+     * changes continues to apply, but it differs between `public` and
+     * `secret` because the two travel through entirely different
+     * write/read paths:
+     *
+     *   - `settings.public` goes through `resolvePluginSettings`
+     *     (`packages/ampless/src/plugin-settings.ts`), which iterates
+     *     `manifest.public` and falls back to `field.default` per
+     *     field. So for public fields, additions resolve via `default`,
+     *     deletions become orphan KvStore rows that the resolver
+     *     silently skips, and incompatible type changes fall through
+     *     to `default` when the stored value fails validation.
+     *   - `settings.secret` is never read by `resolvePluginSettings`.
+     *     The admin UI writes individual values through the
+     *     `setPluginSecret` AppSync mutation; trusted hooks read them
+     *     individually by key via `ctx.secret<T>(key)` which goes
+     *     directly to the `PluginSecret` DynamoDB table. There is no
+     *     `manifest.default` fallback for secrets (the type forbids
+     *     `default` on secret fields). Additions show up in the admin
+     *     UI when the manifest changes; removals leave the stored
+     *     ciphertext row orphaned (no resolver runs over it); renames
+     *     and type changes mean the old key's stored row is never
+     *     read again until an operator deletes it manually.
+     *
+     * None of these paths produce a signal to the plugin author.
+     *
+     * **Future migration PR**: may persist the active manifest
+     * version somewhere alongside stored values and may compare it
+     * to `manifest.version` at resolve time to detect mismatch. The
+     * exact storage location, comparison timing, and mismatch
+     * response are all design territory for that future PR — this
+     * reservation fixes the field name and type on the manifest,
+     * nothing more.
+     *
+     * Important scope distinction: this reservation covers the
+     * `version` *field name and type* on `PluginSettingsManifest`
+     * only. The actual migration mechanism (a `migrate` hook, an
+     * admin-driven flow, batch resolve-time-rewrite, etc.) is a
+     * separate design that lands with its own PR. Declaring
+     * `version` today does NOT pre-wire a migration body — when the
+     * future migration PR ships, plugins that want to provide a
+     * migration body will need to re-publish to add it. Existing
+     * plugins that omit `version` are unaffected by this addition;
+     * plugins that want to participate in the future migration
+     * detection path can opt in today by declaring `version: 1`,
+     * instead of having to re-publish later just to add the
+     * version declaration once the migration PR ships. The
+     * migration body itself (and any future `migrate` hook
+     * signature) is NOT reserved by this PR.
+     *
+     * Recommended values: positive integer, start at 1. Declare
+     * `version: 1` when the manifest first gains a `version` field,
+     * then bump by 1 on each shape-breaking release. Do NOT use
+     * `0` / negative numbers / floats — the `number` type accepts
+     * them but the semantics for those values are reserved for the
+     * future migration PR (`0` may be conflated with "no version
+     * declared" / legacy / pre-v1). Skip the field entirely if you
+     * do not care about migration support (the default, current
+     * behaviour).
+     */
+    version?: number;
 }
 interface AmplessPlugin {
     name: string;
@@ -934,6 +1030,52 @@ interface AmplessPlugin {
     hooks?: {
         [K in EventType]?: PluginEventHandler<K>;
     };
+    /**
+     * Lifecycle hook called when this plugin is removed from
+     * `cms.config.ts` (Phase 1 reservation: runtime no-op).
+     *
+     * Today the runtime does not detect plugin removal and does not
+     * invoke this hook — orphan data left behind by an uninstalled
+     * plugin must be cleaned up manually by the operator. A future
+     * lifecycle-dispatch PR will need to solve the underlying
+     * problem that a plugin that has been deleted from `cms.config.ts`
+     * no longer has a callable factory in memory — `Config.plugins`
+     * (see `packages/ampless/src/types.ts`) only carries currently-
+     * active plugin objects. Possible future approaches:
+     *
+     *   - Two-stage `cms.config.ts` flag — `{ plugin: myPlugin(), pendingRemoval: true }`
+     *     keeps the plugin loadable while the runtime calls `uninstall`,
+     *     then the operator removes the entry once cleanup succeeds.
+     *   - Explicit `npx ampless uninstall <name>` CLI command — keeps
+     *     the plugin imported during the call by reading the prior
+     *     `cms.config.ts` entry, fires `uninstall`, then mutates the
+     *     file.
+     *   - Persist prior manifest + `packageName` to DDB/disk so the
+     *     runtime can `await import(packageName)` to re-acquire the
+     *     factory — assumes the npm package is still installed.
+     *
+     * The exact mechanism is deferred to the lifecycle-dispatch PR.
+     * What this reservation locks in: when `uninstall` does fire,
+     * it runs in a trusted-Lambda IAM context with cleanup grants for
+     * the five plugin-owned data areas (see
+     * docs/architecture/08-plugin-architecture.md
+     * §"Plugin-owned data areas"). Idempotency is the plugin author's
+     * responsibility — the hook may be invoked more than once
+     * (SQS at-least-once or operator-retry).
+     *
+     * **Phase 1 reservation scope**: only the hook name and signature
+     * are reserved. The ctx does NOT yet carry cleanup helpers
+     * (`deletePublicAsset` / `deletePluginSetting` /
+     * `deletePluginSecret`) — writing `await ctx.deletePublicAsset(...)`
+     * today is a TS error. The recommended Phase 1 declaration is an
+     * **empty body** (`async (_ctx) => {}`); the actual cleanup body
+     * lands when the lifecycle-dispatch PR adds the helpers. Plugins
+     * that declared the empty-body uninstall today will pick up the
+     * cleanup invocation events without re-publishing for the signature
+     * change, but a re-publish is required to add the actual cleanup
+     * body.
+     */
+    uninstall?: (ctx: PluginUninstallContext) => Promise<void>;
     /**
      * Per-post metadata generator. Pure function, called from Next.js
      * generateMetadata(). Must not have side effects.
@@ -1551,4 +1693,4 @@ declare function pickDefaultEntrypoint(files: readonly {
 
 declare const VERSION = "0.0.1";
 
-export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginHookResult, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };
+export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginHookResult, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUninstallContext, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };

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

@@ -185,7 +185,11 @@ interface AmplessPlugin {
   publicBodyForPost?(post: Post, ctx): readonly PublicPostBodyDescriptor[]
   publicHtmlForPost?(post: Post, ctx): readonly PublicPostHtmlDescriptor[]
   ogImage?: OgImageConfig
-  settings?: { public?: readonly PluginSettingField[] }
+  settings?: {
+    public?: readonly PluginSettingField[]
+    secret?: readonly PluginSecretField[]
+    version?: number  // Phase 1 reservation; runtime ignores
+  }
 }
 ```
 
@@ -973,6 +977,149 @@ admin は再デプロイなしにいつでも secret をローテーションで
 
 ---
 
+## 9b. プラグインのデータの保存場所
+
+プラグインが所有するデータは以下の 5 つのストレージ領域に置かれる可能性があり、**現状の書き込み経路は領域ごとに異なります**。3 つのファミリに分かれます:
+
+- **KvStore** — admin/editor が AppSync 経由で書き込みます。プラグインの hook には KvStore write helper は提供されていません。
+- **PluginSecret + PluginSecretIndicator** — `plugin-secret-handler` Lambda が書き込みます。admin/editor が `setPluginSecret` / `clearPluginSecret` AppSync mutation を呼ぶと、handler Lambda が DDB に書く流れです。trusted processor は `ctx.secret<T>()` で `PluginSecret` を読み取りますが、どちらの secret テーブルにも書き込みません。
+- **S3 `public/plugins/{instanceId ?? name}/*`** — trusted Lambda の hook context (`ctx.writePublicAsset(...)`) から書き込みます。プラグインの hook が直接書き込めるのはこの領域だけです。
+
+それ以外 — `Post`、`Page`、`Media`、`PostTag` DynamoDB テーブル、`public/site-settings.json` S3 ミラー、他プラグインの namespace — への書き込みは禁止です。現状 runtime が強制しているわけではなく、信頼（および将来の IAM 強化）によって担保されます。
+
+| 領域 | パス / 識別子 | アクセスレベル | Phase |
+|---|---|---|---|
+| KvStore（admin 設定） | DynamoDB `pk='siteconfig'`、`sk='plugins.<instanceId>.<fieldKey>'` | admin/editor が AppSync 経由で書く（プラグインの hook context には KvStore write helper は現状提供されていない） | Phase 2 |
+| KvStore（runtime 状態/キャッシュ） | DynamoDB `pk='pluginstate:<plugin>:...'`（TTL 任意） | admin/editor が AppSync 経由で書く（プラグインの hook context には KvStore write helper は現状提供されていない） | 現行 |
+| PluginSecret | DynamoDB `PluginSecret` テーブル、`sk='plugins.<instanceId>.<fieldKey>'` | `trusted` 限定（IAM 専用 AppSync 認証） | Phase 6a |
+| PluginSecretIndicator | DynamoDB `PluginSecretIndicator` テーブル、`sk='plugins.<instanceId>.<fieldKey>'` | `trusted` + admin/editor（indicator 読み取り） | Phase 6a |
+| S3 プラグイン成果物 | `public/plugins/{instanceId ?? name}/*` | `trusted` 限定（`writePublicAsset`） | Phase 3 |
+
+**cleanup は自動ではありません。** `cms.config.ts` からプラグインを外しても、5 領域のデータは自動削除されません。将来の lifecycle-dispatch PR が `uninstall` フックの起動メカニズムを追加するまで（§9c 参照）、オペレータによる手動削除が必要です。
+
+**独自 DynamoDB テーブル。** プラグインが ampless スキーマ外に独自の DynamoDB テーブルを持つ場合、lifecycle 管理（アンインストール時の cleanup を含む）はプラグイン著者の責任です。ampless は外部テーブルを把握しておらず、将来の `uninstall` cleanup grant は上記 5 領域のみをカバーします。
+
+詳細な設計根拠と IAM grant 設計については [`docs/architecture/08-plugin-architecture.ja.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.ja.md#プラグインが所有するデータ領域) を参照してください。
+
+---
+
+## 9c. `uninstall` フック（Phase 1 予約）
+
+`AmplessPlugin.uninstall` は **Phase 1 型予約** です — 現在 runtime はこれを呼び出しません。hook 名とシグネチャをプラグインコードが出回る前に確定し、将来の lifecycle-dispatch PR が名前・形を変更せずに起動を配線できるようにするのが目的です。
+
+**Phase 1 スコープ**: hook 名とシグネチャのみ予約。`ctx` には cleanup helper (`deletePublicAsset` / `deletePluginSetting` / `deletePluginSecret`) がまだありません — 今日 `await ctx.deletePublicAsset(...)` と書くと TypeScript エラーです。これらの helper が lifecycle-dispatch PR で追加される際は `PluginUninstallContext` への追加（additive）であり、空のボディを宣言済みのプラグインへの破壊変更はありません。
+
+**今日の推奨宣言** — 空のボディ:
+
+```ts
+// 例: S3 成果物と secret を書く trusted plugin
+definePlugin({
+  name: 'my-trusted-plugin',
+  apiVersion: 1,
+  trust_level: 'trusted',
+  capabilities: ['eventHooks', 'writePublicAsset', 'secretSettings'],
+  hooks: { 'content.published': async (_evt, ctx) => { /* ... */ } },
+  uninstall: async (_ctx) => {
+    // Phase 1 予約: runtime は今日このフックを呼び出しません。
+    // また `ctx` には cleanup helper
+    // (`deletePublicAsset` / `deletePluginSetting` /
+    // `deletePluginSecret`) がまだありません。
+    // 空ボディを宣言しておくのが forward-compat の推奨形です —
+    // 将来 lifecycle-dispatch PR がリリースされたとき、helper が
+    // `PluginUninstallContext` に追加され、そこで cleanup ボディを
+    // 実装します。今日の空宣言を再パブリッシュしなくても呼び出し
+    // イベントは受け取れますが、実際の cleanup ボディを追加するには
+    // 再パブリッシュが必要です。
+  },
+})
+```
+
+**冪等性。** lifecycle-dispatch PR がリリースされると、`uninstall` フックは trusted Lambda の IAM コンテキストで実行されます。SQS 配送は at-least-once なので cleanup ボディが複数回実行される可能性があります。安全にリトライできるよう設計してください（S3 の `deleteObject` は冪等、DDB の conditional delete も key が消えていれば safe）。
+
+---
+
+## 9d. settings の形状を変えるとき（Phase 1 予約）
+
+### 今日の挙動: `public` と `secret` は別の経路を辿る
+
+形状変更は今日の runtime で silently 吸収されますが、実際の挙動は `settings.public` と `settings.secret` で異なります。両者は完全に別の write/read パスを使っているためです。
+
+#### `settings.public`（`resolvePluginSettings` の寛容な resolver）
+
+`resolvePluginSettings`（[packages/ampless/src/plugin-settings.ts](packages/ampless/src/plugin-settings.ts)）は `manifest.public` のみをイテレートし、field ごとに `field.default` にフォールバックします。resolver は `manifest.secret` を一切見ません。
+
+| 変更 | 今日の挙動（public フィールド） |
+|---|---|
+| **フィールド追加** | 新フィールドは `manifest.default` から解決されます。ストレージに値がないため default が使われます。 |
+| **フィールド削除** | KvStore に orphan row が残ります。`resolvePluginSettings` は現在の manifest にない key を silently skip します。 |
+| **フィールド改名**（`endpoint` → `url`） | 削除 + 追加として扱われます。旧値は到達不能（orphan）になり、新フィールドは `default` から解決されます。 |
+| **型を非互換に変更** | 新しい validator がストレージの値に対して実行されます。通過すれば値が使われ、失敗すれば `default`（または `undefined`）にフォールバックします。 |
+
+#### `settings.secret`（admin UI + `PluginSecret` + `ctx.secret()`、寛容な resolver なし）
+
+Secret フィールドは `resolvePluginSettings` から一切読まれません。別の経路を辿ります:
+
+- admin UI が `setPluginSecret` AppSync mutation 経由で値を 1 つずつ書き、`plugin-secret-handler` Lambda が暗号化して `PluginSecret` DynamoDB テーブルに格納
+- trusted hook が `ctx.secret<T>(key)` で key 単位で直接 `PluginSecret` から復号読み取り
+- `PluginSecretField` 型は `default` を持てない（型レベルで禁止）。manifest レベルのフォールバックは存在しない
+
+| 変更 | 今日の挙動（secret フィールド） |
+|---|---|
+| **フィールド追加** | admin UI に新フィールドが表示されます。admin が値を設定するまで `ctx.secret<T>(key)` は `undefined` を返します。 |
+| **フィールド削除** | admin UI から消えますが、`PluginSecret` 内の暗号化された row は orphan として残ります。resolver は走らないため、operator が手動で削除する必要があります。 |
+| **フィールド改名** | 旧 key の暗号化された row は orphan になります（resolver / cleanup なし）。新 key は未設定として表示され、admin が新 key に値を入れ直す必要があります。 |
+| **型を非互換に変更** | `validatePluginSettingValue` は write 時のみ実行されます。既存の暗号化値は read 時には影響を受けず、`ctx.secret<T>(key)` は最後に書かれた値を返します。新しい入力を admin が保存しようとすると新 validator で reject される、というだけです。 |
+
+これらのケースでエラーや警告は発生しません。形状変更後の挙動を確認するには、プラグイン著者が手動でストレージの値を確認する必要があります。
+
+### `version` 予約について
+
+`PluginSettingsManifest.version?: number` は **Phase 1 型予約** です。runtime は今日このフィールドを読みません。宣言しても上記の寛容な resolver の挙動は変わりません。
+
+この予約は、将来の migration PR がストレージの値に manifest の version をどこかに保存し、resolve 時に `manifest.version` と比較してミスマッチを検出できるようにするためのものです。ミスマッチ時の応答（warn / skip / in-place migration / admin 主導フローなど）はその future PR の設計領域です。
+
+**`version` を宣言しても今日保証されないこと:**
+
+- migration ボディは実行されません。
+- ストレージの値の再検証・再 default も行われません。
+- `migrate` hook のシグネチャは予約されていません（それは別の future 設計）。
+
+**`version` を今日宣言することで得られるもの:**
+
+- その PR がリリースされた後に `version` フィールドを追加するためだけの再パブリッシュが不要になります（将来の migration 検出パスに最初から参加できます）。
+- manifest に versioned な形状であることを将来のメンテナーに伝えます。
+
+### 推奨パターン
+
+| シナリオ | 推奨 |
+|---|---|
+| 追加のみの変更（新しいオプションフィールド、default あり） | `version` の bump 不要。寛容な resolver が吸収します。 |
+| 非互換変更（改名、型変更、意味的変化） | `version` を 1 増やします。 |
+| 既存 manifest に初めて `version` を追加する | `version: 1` から始めます。 |
+
+**正の整数、1 始まりを使用してください。** `0`、負数、小数は使わないでください。`number` 型はそれらを受け入れますが、将来の migration PR が `0` / undefined に特別な意味（legacy / pre-v1 との混同を避けるため）を予約する可能性があります。
+
+### コード例
+
+```ts
+definePlugin({
+  name: 'my-plugin',
+  apiVersion: 1,
+  trust_level: 'untrusted',
+  capabilities: ['adminSettings'],
+  settings: {
+    version: 2,           // ← Phase 1 reservation。今日の runtime は無視します。
+    public: [
+      { type: 'url', key: 'webhookUrl', label: 'Webhook URL', required: true },
+    ],
+  },
+})
+```
+
+将来の migration PR がリリースされると、すでに `version` を宣言しているプラグインは自動的に検出パスに乗ります。実際の migration ボディを提供したいプラグインは、その PR がリリースされてから再パブリッシュしてボディを追加する必要があります。`version` を省略したプラグインは引き続き現在の寛容な resolver の挙動のままで変化ありません。
+
+---
+
 ## 10. ウォークスルー: GA4 を Phase 1 から Phase 2 に移行する
 
 Phase 1 の GA4 プラグインは measurement ID を constructor 引数で受けていました。Phase 2 では後方互換のためにその引数を残しつつ、値は `ctx.setting()` 経由で読みます。

package/docs/plugin-author-guide.md

@@ -213,7 +213,11 @@ interface AmplessPlugin {
   publicBodyForPost?(post: Post, ctx): readonly PublicPostBodyDescriptor[]
   publicHtmlForPost?(post: Post, ctx): readonly PublicPostHtmlDescriptor[]
   ogImage?: OgImageConfig
-  settings?: { public?: readonly PluginSettingField[] }
+  settings?: {
+    public?: readonly PluginSettingField[]
+    secret?: readonly PluginSecretField[]
+    version?: number  // Phase 1 reservation; runtime ignores
+  }
 }
 ```
 
@@ -1323,6 +1327,208 @@ describe('webhookPlugin signing', () => {
 
 ---
 
+## 9b. Where your plugin's data lives
+
+Plugin-owned data may live in the five storage areas listed below; the
+**current write paths differ by area** and fall into three families:
+
+- **KvStore** — admin/editor write through AppSync. Plugin hooks have no
+  KvStore write helper today.
+- **PluginSecret + PluginSecretIndicator** — written by the
+  `plugin-secret-handler` Lambda, which is invoked by admin/editor through
+  the `setPluginSecret` / `clearPluginSecret` AppSync mutations. The
+  trusted processor reads `PluginSecret` via `ctx.secret<T>()` but does
+  NOT write to either secret table.
+- **S3 `public/plugins/{instanceId ?? name}/*`** — written by the trusted
+  Lambda's hook context (`ctx.writePublicAsset(...)`). This is the only
+  area a plugin hook writes to directly today.
+
+All other areas — the `Post`, `Page`, `Media`, and `PostTag` DynamoDB
+tables, the `public/site-settings.json` S3 mirror, and any other plugin's
+namespace — are off-limits. The runtime does not enforce this today; it is
+a contract enforced by trust (and future IAM hardening).
+
+| Area | Path / identifier | Access level | Phase |
+|---|---|---|---|
+| KvStore (admin settings) | DynamoDB `pk='siteconfig'`, `sk='plugins.<instanceId>.<fieldKey>'` | admin/editor via AppSync; plugin hook write helper is not provided today | Phase 2 |
+| KvStore (runtime state/cache) | DynamoDB `pk='pluginstate:<plugin>:...'` with optional TTL | admin/editor via AppSync; plugin hook write helper is not provided today | Current |
+| PluginSecret | DynamoDB `PluginSecret` table, `sk='plugins.<instanceId>.<fieldKey>'` | `trusted` only (IAM-only AppSync auth) | Phase 6a |
+| PluginSecretIndicator | DynamoDB `PluginSecretIndicator` table, `sk='plugins.<instanceId>.<fieldKey>'` | `trusted` + admin/editor (read indicator) | Phase 6a |
+| S3 plugin assets | `public/plugins/{instanceId ?? name}/*` | `trusted` only (`writePublicAsset`) | Phase 3 |
+
+**Cleanup is not automatic.** Removing a plugin from `cms.config.ts` leaves
+orphan data in all five areas. Manual operator cleanup is required until the
+future lifecycle-dispatch PR ships the invocation mechanism for the `uninstall`
+hook (see §9c below).
+
+**Custom DynamoDB tables.** If your plugin provisions its own DynamoDB table
+outside the ampless schema, lifecycle management (including cleanup on uninstall)
+is your responsibility. ampless has no visibility into external tables and the
+future `uninstall` cleanup grants cover only the five areas above.
+
+See [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#plugin-owned-data-areas)
+for the full rationale and the IAM grant design.
+
+---
+
+## 9c. `uninstall` hook (Phase 1 reservation)
+
+`AmplessPlugin.uninstall` is a **Phase 1 type reservation** — the runtime does
+not call it today. Its purpose is to lock in the hook name and signature before
+any plugin code ships, so the future lifecycle-dispatch PR can wire the
+invocation without renaming or reshaping anything.
+
+**Phase 1 scope**: only the hook name and signature are reserved. The `ctx`
+does **not** yet carry cleanup helpers (`deletePublicAsset` /
+`deletePluginSetting` / `deletePluginSecret`) — writing
+`await ctx.deletePublicAsset(...)` today is a TypeScript error. When those
+helpers land (in the lifecycle-dispatch PR), they are added to
+`PluginUninstallContext` additively, with no breaking change to plugins that
+declared an empty body in advance.
+
+**Recommended declaration today** — an empty body:
+
+```ts
+// Example: a trusted plugin that writes assets and stores secrets
+definePlugin({
+  name: 'my-trusted-plugin',
+  apiVersion: 1,
+  trust_level: 'trusted',
+  capabilities: ['eventHooks', 'writePublicAsset', 'secretSettings'],
+  hooks: { 'content.published': async (_evt, ctx) => { /* ... */ } },
+  uninstall: async (_ctx) => {
+    // Phase 1 reservation: the runtime does not invoke this hook
+    // today, AND `ctx` does not yet carry cleanup helpers
+    // (`deletePublicAsset` / `deletePluginSetting` /
+    // `deletePluginSecret`). Declaring an empty body is the
+    // recommended forward-compat shape — when the future
+    // lifecycle-dispatch PR ships, the helpers land on
+    // `PluginUninstallContext` additively, and you fill in the
+    // body THEN. Plugins that shipped the empty declaration
+    // today do not need to re-publish for the signature change,
+    // but a re-publish is required to add the actual cleanup
+    // body.
+  },
+})
+```
+
+**Idempotency.** When the lifecycle-dispatch PR ships, the `uninstall` hook
+runs in a trusted-Lambda IAM context. The SQS delivery is at-least-once, so
+your cleanup body may run more than once — design it to be safe to retry
+(e.g. `deleteObject` is idempotent on S3; a conditional `delete` on DDB is
+safe if the key is already gone).
+
+---
+
+## 9d. When you change settings shape (Phase 1 reservation)
+
+### What happens today: `public` and `secret` travel through different paths
+
+Shape changes are absorbed silently by today's runtime, but the actual
+behaviour differs between `settings.public` and `settings.secret` because
+they use entirely different write/read paths.
+
+#### `settings.public` (lenient resolver via `resolvePluginSettings`)
+
+`resolvePluginSettings` ([packages/ampless/src/plugin-settings.ts](packages/ampless/src/plugin-settings.ts))
+iterates `manifest.public` and falls back to `field.default` per field. The
+resolver never looks at `manifest.secret`.
+
+| Change | Behaviour today (public fields) |
+|---|---|
+| **Field added** | New field resolves via `manifest.default` — stored value is absent, default takes over. |
+| **Field deleted** | Orphan row remains in KvStore. `resolvePluginSettings` silently skips keys that are not in the current manifest. |
+| **Field renamed** (`endpoint` → `url`) | Treated as deletion + addition: old value is unreachable (orphan), new field resolves via `default`. |
+| **Type changed incompatibly** | New validator runs on the stored value. If it passes, the value is used. If it fails, falls through to `default` (or `undefined`). |
+
+#### `settings.secret` (admin UI + `PluginSecret` + `ctx.secret()`, no lenient resolver)
+
+Secret fields are never read by `resolvePluginSettings`. They travel a
+separate path:
+
+- The admin UI writes individual values through the `setPluginSecret`
+  AppSync mutation, which the `plugin-secret-handler` Lambda encrypts and
+  stores in the `PluginSecret` DynamoDB table.
+- Trusted hooks read them individually by key via `ctx.secret<T>(key)`,
+  which goes directly to `PluginSecret` and decrypts.
+- The `PluginSecretField` type forbids `default` — there is no
+  manifest-level fallback for secret values.
+
+| Change | Behaviour today (secret fields) |
+|---|---|
+| **Field added** | New field appears in the admin UI. Until an admin sets a value, `ctx.secret<T>(key)` returns `undefined`. |
+| **Field deleted** | The field disappears from the admin UI, but the encrypted row in `PluginSecret` is orphaned. No resolver runs over it; an operator must delete it manually. |
+| **Field renamed** | Old key's encrypted row is orphaned (no resolver / cleanup). The new key shows up unset. Admin must re-enter the value under the new key. |
+| **Type changed incompatibly** | `validatePluginSettingValue` only runs at write time, so an existing stored ciphertext is unaffected on read; `ctx.secret<T>(key)` returns whatever was last written. A re-validate on admin save would reject incompatible new input. |
+
+No error or warning is produced in any of these cases. Plugin authors must
+inspect their stored values manually if they need to verify behaviour
+after a shape change.
+
+### The `version` reservation
+
+`PluginSettingsManifest.version?: number` is a **Phase 1 type
+reservation** — the runtime does NOT read it today. Declaring it has no
+effect on the lenient resolver above.
+
+The reservation exists so that a future migration PR may persist the
+active manifest version somewhere alongside stored values and compare it to
+`manifest.version` at resolve time to detect mismatch. The exact mismatch
+response (warn / skip / migrate in-place / trigger an admin-driven flow) is
+design territory for that future PR.
+
+**What declaring `version` today does NOT promise:**
+
+- It does NOT trigger any migration body.
+- It does NOT cause the runtime to re-validate or re-default stored values.
+- It does NOT reserve a `migrate` hook signature — that is a separate future
+  design.
+
+**What declaring `version` today does do:**
+
+- It positions the plugin to be picked up by the future migration detection
+  path, without requiring a re-publish just to add the `version` field once
+  that PR ships.
+- It communicates intent to future maintainers that this manifest has a
+  versioned shape.
+
+### Recommended pattern
+
+| Scenario | Recommendation |
+|---|---|
+| Additive change only (new optional field, default provided) | No `version` bump needed. Lenient resolver handles it. |
+| Non-additive change (rename, incompatible type change, semantic shift) | Bump `version` by 1. |
+| First time adding `version` to an existing manifest | Start at `version: 1`. |
+
+**Use positive integers, starting at 1.** Do NOT use `0`, negative numbers,
+or floats — the `number` type accepts them but the future migration PR may
+reserve special semantics for `0` / undefined (legacy / pre-v1 conflation).
+
+### Code example
+
+```ts
+definePlugin({
+  name: 'my-plugin',
+  apiVersion: 1,
+  trust_level: 'untrusted',
+  capabilities: ['adminSettings'],
+  settings: {
+    version: 2,           // ← Phase 1 reservation. Today runtime ignores.
+    public: [
+      { type: 'url', key: 'webhookUrl', label: 'Webhook URL', required: true },
+    ],
+  },
+})
+```
+
+When a future migration PR ships, plugins that have already declared
+`version` will be on the detection path automatically. Plugins that want to
+provide an actual migration body will need to re-publish after that PR ships
+to add the body. Plugins that omit `version` entirely continue with the
+current lenient-resolver behaviour — no change.
+
+---
+
 ## 10. Walk-through: migrating GA4 from Phase 1 to Phase 2
 
 The Phase 1 GA4 plugin took the measurement ID through a

package/package.json

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