ampless 1.0.0-alpha.36 → 1.0.0-alpha.38

package/dist/index.d.ts

@@ -896,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;
@@ -1287,6 +1361,12 @@ interface Config {
      * field is absent.
      */
     cache?: CacheConfig;
+    /**
+     * Post revision-history knobs. The event-dispatcher Lambda snapshots
+     * each post save into the `PostHistory` table; this controls how long
+     * those snapshots are retained.
+     */
+    history?: HistoryConfig;
 }
 /**
  * Tunables for middleware-computed `Cache-Control`. See
@@ -1311,6 +1391,20 @@ interface CacheConfig {
      */
     deepTtlSeconds?: number;
 }
+/**
+ * Post revision-history tunables, read by the event-dispatcher Lambda
+ * (via the template shell) when snapshotting each post save.
+ */
+interface HistoryConfig {
+    /**
+     * Days to retain each post revision before DynamoDB TTL deletes it.
+     * Default 0 = keep forever (no `ttl` attribute is written). DynamoDB TTL
+     * deletes within ~48h after expiry, so effective retention is
+     * retentionDays + up to ~2 days. Changing this only affects revisions
+     * written afterward — existing rows keep their original expiry.
+     */
+    retentionDays?: number;
+}
 type Role = 'reader' | 'editor' | 'admin';
 interface AuthContext {
     userId: string;
@@ -1341,6 +1435,45 @@ interface ListOptions {
 type CreatePostInput = Omit<Post, 'postId'> & {
     postId?: string;
 };
+/**
+ * One in-memory snapshot of a Post at save time, read back from the
+ * `PostHistory` table (written by the event-dispatcher Lambda on each
+ * Post INSERT/MODIFY — see packages/backend/src/events/dispatcher.ts).
+ *
+ * `body` is already decoded from its AWSJSON wire form (the provider
+ * runs `decodeAwsJson` before handing the row up), so it matches the
+ * `Post['body']` shape for the declared `format`.
+ */
+interface PostRevision {
+    /** Deterministic id `${postId}#${revisedAt}` — unique per save. */
+    postHistoryId: string;
+    postId: string;
+    /** ISO 8601 save time. Also the `byPost` GSI sort key (newest-first). */
+    revisedAt: string;
+    title?: string;
+    slug?: string;
+    excerpt?: string;
+    format?: ContentFormat;
+    body?: unknown;
+    status?: PostStatus;
+    publishedAt?: string;
+    tags?: string[];
+    metadata?: PostMetadata;
+}
+/** Pagination options for `listPostHistory`. */
+interface ListPostHistoryOptions {
+    limit?: number;
+    nextToken?: string;
+}
+/**
+ * A page of revisions newest-first. `nextToken` feeds straight back into
+ * `ListPostHistoryOptions.nextToken` for the next page; `undefined` means
+ * no more rows.
+ */
+interface PostRevisionConnection {
+    items: PostRevision[];
+    nextToken?: string;
+}
 interface PostsProvider {
     list(opts?: ListOptions): Promise<Post[]>;
     get(slug: string): Promise<Post | null>;
@@ -1348,6 +1481,7 @@ interface PostsProvider {
     create(data: CreatePostInput): Promise<Post>;
     update(postId: string, data: Partial<Post>): Promise<Post>;
     remove(postId: string): Promise<void>;
+    listPostHistory(postId: string, options?: ListPostHistoryOptions): Promise<PostRevisionConnection>;
 }
 declare function setPostsProvider(p: PostsProvider): void;
 declare function hasPostsProvider(): boolean;
@@ -1357,6 +1491,13 @@ declare function getPostById(postId: string): Promise<Post | null>;
 declare function createPost(data: CreatePostInput): Promise<Post>;
 declare function updatePost(postId: string, data: Partial<Post>): Promise<Post>;
 declare function deletePost(postId: string): Promise<void>;
+/**
+ * List a post's revision history, newest-first. Backed by the
+ * `PostHistory` `byPost` GSI. Requires a configured provider (the dummy
+ * fallback has no history) — returns an empty connection otherwise so
+ * callers (e.g. the admin history panel) degrade gracefully.
+ */
+declare function listPostHistory(postId: string, options?: ListPostHistoryOptions): Promise<PostRevisionConnection>;
 
 interface KvItem<T = unknown> {
     pk: string;
@@ -1619,4 +1760,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 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 };
+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 HistoryConfig, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type ListPostHistoryOptions, 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 PostRevision, type PostRevisionConnection, 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, listPostHistory, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };

package/dist/index.js

@@ -83,6 +83,10 @@ async function deletePost(postId) {
   if (!provider) throw new Error("No posts provider configured. Call setPostsProvider() first.");
   return provider.remove(postId);
 }
+async function listPostHistory(postId, options) {
+  if (!provider) return { items: [] };
+  return provider.listPostHistory(postId, options);
+}
 
 // src/kv.ts
 var store = null;
@@ -794,6 +798,7 @@ export {
   hasPostsProvider,
   isTagListUrl,
   isValidPluginKey,
+  listPostHistory,
   listPosts,
   listSiteSettings,
   mimeTypeFor,

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
+  }
 }
 ```
 
@@ -1034,6 +1038,88 @@ definePlugin({
 
 ---
 
+## 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
+  }
 }
 ```
 
@@ -1416,6 +1420,115 @@ 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.36",
+  "version": "1.0.0-alpha.38",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",