@agent-native/core 0.96.0 → 0.97.0

package/corpus/templates/content/AGENTS.md

@@ -91,60 +91,61 @@ cd templates/content && pnpm action <name> [args]
 
 ### Document Operations
 
-| Action                                      | Args                                                                                                                                                           | Purpose                                                                                                                                                                           |
-| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `list-documents`                            | `[--format json]`                                                                                                                                              | List document metadata/tree; no full bodies                                                                                                                                       |
-| `export-content-source`                     | `[--format json]`                                                                                                                                              | Export editable docs as `content/*.mdx` source files                                                                                                                              |
-| `import-content-source`                     | `--files <json> [--dryRun true\|false]`                                                                                                                        | Import `.md`/`.mdx` source files into editable docs                                                                                                                               |
-| `list-builder-docs`                         | `[--model docs-content\|blog-article] [--limit <n>]`                                                                                                           | List Builder docs/blog entries available for `.builder.mdx` pull                                                                                                                  |
-| `pull-builder-doc`                          | `--model <model> --entryId <builder-entry-id> [--dryRun true\|false]`                                                                                          | Pull one Builder entry into Content and return `.builder.mdx` plus `content/builder/.raw` sidecar files                                                                           |
-| `check-builder-doc`                         | `--files <json> [--path <file.builder.mdx>]` or `--documentId <id>`                                                                                            | Validate Builder MDX round-trip, sidecar hashes, and remote conflict status before push                                                                                           |
-| `push-builder-doc`                          | `--files <json> [--path <file.builder.mdx>] [--dryRun true\|false]`                                                                                            | Guarded Builder autosave PATCH for the safe Builder test model; never publishes                                                                                                   |
-| `navigate`                                  | `--path <path>` or `--documentId <id>` or `--databaseId <id>`                                                                                                  | Open a route, document page, or database page in the UI                                                                                                                           |
-| `search-documents`                          | `--query <text> [--format json]`                                                                                                                               | Search by title/content and return snippets                                                                                                                                       |
-| `get-document`                              | `--id <id> [--format json]`                                                                                                                                    | Get a single document with content                                                                                                                                                |
-| `pull-document`                             | `--id <id> [--format markdown\|text]`                                                                                                                          | Collab-aware "ingest the final" read                                                                                                                                              |
-| `create-document`                           | `--title <text> [--content] [--parentId] [--icon]`                                                                                                             | Create a new document                                                                                                                                                             |
-| `edit-document`                             | `--id <id> --find <text> --replace <text>`                                                                                                                     | Surgical text edit (preferred for modifications)                                                                                                                                  |
-| `edit-document`                             | `--id <id> --edits <json>`                                                                                                                                     | Batch surgical text edits                                                                                                                                                         |
-| `update-document`                           | `--id <id> [--title] [--content] [--icon]`                                                                                                                     | Full rewrite of document fields                                                                                                                                                   |
-| `share-local-file-document`                 | `--id <local-file-document-id>`                                                                                                                                | Create or refresh a DB-backed shareable copy of a local file document                                                                                                             |
-| `remove-local-file-source`                  | `[--sourceRootPath <path>]`                                                                                                                                    | Unlink local-file sources from Content without deleting local Markdown/MDX files                                                                                                  |
-| `list-local-component-files`                |                                                                                                                                                                | List registered local MDX component source files                                                                                                                                  |
-| `write-local-component-file`                | `--workspaceId <id> --path <relative-component-path> --content <source>`                                                                                       | Create or update a file in a registered local `components/` folder                                                                                                                |
-| `create-content-database`                   | `[--documentId <id>] [--parentId <id>] [--title <text>]`                                                                                                       | Create a database page or convert an existing page into a database                                                                                                                |
-| `create-inline-content-database`            | `--hostDocumentId <id> [--title <text>]`                                                                                                                       | Create a database owned by an inline database block in the host document                                                                                                          |
-| `get-content-database`                      | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Get a database table with property schema and item pages                                                                                                                          |
-| `list-trashed-content-databases`            |                                                                                                                                                                | List soft-deleted databases visible in the sidebar Trash surface                                                                                                                  |
-| `restore-content-database`                  | `--databaseId <id>`                                                                                                                                            | Restore a soft-deleted database from the sidebar Trash surface                                                                                                                    |
-| `get-content-database-source`               | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Inspect local/no-source or source-backed status, mappings, row identity, freshness, and change sets                                                                               |
-| `attach-content-database-source`            | `--databaseId <id>` or `--documentId <id> [--sourceType mock\|builder-cms] [--sourceName] [--sourceTable] [--relationshipMode items\|details] [--join <json>]` | Attach a source binding; use `items` to add more rows and `details` to match a source onto existing rows                                                                          |
-| `change-content-database-source-role`       | `--databaseId <id>` or `--documentId <id> --sourceId <id> --relationshipMode items\|details [--join <json>]`                                                   | Change an attached source between adding rows and adding matched detail columns without removing the source                                                                       |
-| `refresh-content-database-source`           | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Refresh the read-only source status envelope; large Builder CMS sources may return a partial fetch, and another refresh continues loading remaining rows                          |
-| `process-builder-body-hydration`            | `--sourceId <id> [--documentId <id>] [--limit <n>]`                                                                                                            | Hydrate queued Builder article bodies into readable Content markdown with preserved source-component markers                                                                      |
-| `set-content-database-source-write-mode`    | `--databaseId <id>` or `--documentId <id> --liveWritesEnabled true\|false [--allowedWriteModes <json>]`                                                        | Enable/disable per-source Builder live writes; enabling is allowed only for `agent-native-blog-article-test` with explicit modes                                                  |
-| `stage-builder-revision`                    | `--databaseId <id>` or `--documentId <id>`                                                                                                                     | Stage pending local Builder CMS changes as a local-only save-revision record; never calls Builder                                                                                 |
-| `review-content-database-source-change-set` | `--databaseId <id>` or `--documentId <id> --changeSetId <id> --decision approve\|reject [--note]`                                                              | Approve or reject a local source change-set review record without provider writes                                                                                                 |
-| `stage-builder-source-bulk-update`          | `--databaseId <id>` or `--documentId <id> --itemIds <json-array>` or `--documentIds <json-array> --field <json> [--sourceId <id>] [--dryRun true\|false]`      | Preview or stage one bounded field update across selected source-backed Builder rows; apply still goes through Builder review/execution                                           |
-| `prepare-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--pushModeConfirmation autosave\|draft\|publish]`                                                | Prepare a dry-run Builder execution gate for approved field/body changes with request semantics/idempotency key; never calls Builder                                              |
-| `validate-builder-source-execution`         | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>]`                                                                         | Validate/replay a prepared Builder execution gate locally as a dry run; never calls Builder                                                                                       |
-| `execute-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>] [--pushModeConfirmation autosave\|draft\|publish]`                       | Execute a guarded live Builder write only when approved, validated, enabled, idempotent, and targeting `agent-native-blog-article-test`                                           |
-| `add-database-item`                         | `--databaseId <id> [--title <text>] [--propertyValues <json>]`                                                                                                 | Add a page row to a database, optionally seeding property values                                                                                                                  |
-| `submit-content-database-form`              | `--databaseId <id> [--viewId <form-view-id>] [--title <text>] [--propertyValues <json>]`                                                                       | Submit one form response atomically; validates required questions, resolves option labels/IDs, writes Blocks correctly, verifies persistence, and returns the exact row page link |
-| `duplicate-database-item`                   | `--itemId <id>` or `--documentId <id> [--title <text>]`                                                                                                        | Duplicate exactly one database row page and its stored property values; for two or more rows, use `duplicate-database-items` once                                                 |
-| `duplicate-database-items`                  | `--databaseId <id>` or `--documentId <databaseDocumentId> --itemIds <json-array>` or `--documentIds <json-array>`                                              | Preferred multi-row duplicate action; duplicate multiple database row pages atomically and return ordered duplicate item/document IDs                                             |
-| `delete-database-items`                     | `--databaseId <id>` or `--documentId <databaseDocumentId> --itemIds <json-array>` or `--documentIds <json-array>`                                              | Preferred multi-row delete action; delete multiple database row pages atomically while preserving `delete-document` admin semantics                                               |
-| `move-database-item`                        | `--itemId <id>` or `--documentId <id> --position <number>`                                                                                                     | Move a database row page to a new zero-based table position                                                                                                                       |
-| `update-content-database-view`              | `--databaseId <id> --viewConfig <json>`                                                                                                                        | Persist database views, sorts, filters, hidden properties, and view settings                                                                                                      |
-| `list-document-properties`                  | `--documentId <id> [--format json]`                                                                                                                            | List Notion-style property definitions and values for a document                                                                                                                  |
-| `configure-document-property`               | `--documentId <id> [--id <propertyId>] --name <name> --type <type> [--visibility always_show\|hide_when_empty\|always_hide]`                                   | Create or update a property definition                                                                                                                                            |
-| `duplicate-document-property`               | `--documentId <id> --propertyId <propertyId>`                                                                                                                  | Duplicate a property definition and its stored values                                                                                                                             |
-| `delete-document-property`                  | `--documentId <id> --propertyId <propertyId>`                                                                                                                  | Delete a property definition and its stored values                                                                                                                                |
-| `set-document-property`                     | `--documentId <id> --propertyId <propertyId> --value <json>`                                                                                                   | Set a document property value (for a `blocks` field, the value is its markdown content)                                                                                           |
-| `reorder-document-property`                 | `--documentId <id> --propertyId <propertyId> --targetPropertyId <id> [--position before\|after]`                                                               | Reorder a property definition within its database (used to reorder Blocks fields on the page)                                                                                     |
-| `set-document-discoverability`              | `--id <id> --hideFromSearch true\|false [--includeChildren true\|false]`                                                                                       | Hide/show an org-accessible document in Organization/search while keeping link access                                                                                             |
-| `move-document`                             | `--id <id> [--parentId] [--position]`                                                                                                                          | Move or reorder a document in the page tree                                                                                                                                       |
-| `delete-document`                           | `--id <id>`                                                                                                                                                    | Delete with recursive children                                                                                                                                                    |
+| Action                                      | Args                                                                                                                                                                                               | Purpose                                                                                                                                                                           |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list-documents`                            | `[--format json]`                                                                                                                                                                                  | List document metadata/tree; no full bodies                                                                                                                                       |
+| `export-content-source`                     | `[--format json]`                                                                                                                                                                                  | Export editable docs as `content/*.mdx` source files                                                                                                                              |
+| `import-content-source`                     | `--files <json> [--dryRun true\|false]`                                                                                                                                                            | Import `.md`/`.mdx` source files into editable docs                                                                                                                               |
+| `list-builder-docs`                         | `[--model docs-content\|blog-article] [--limit <n>]`                                                                                                                                               | List Builder docs/blog entries available for `.builder.mdx` pull                                                                                                                  |
+| `pull-builder-doc`                          | `--model <model> --entryId <builder-entry-id> [--dryRun true\|false]`                                                                                                                              | Pull one Builder entry into Content and return `.builder.mdx` plus `content/builder/.raw` sidecar files                                                                           |
+| `check-builder-doc`                         | `--files <json> [--path <file.builder.mdx>]` or `--documentId <id>`                                                                                                                                | Validate Builder MDX round-trip, sidecar hashes, and remote conflict status before push                                                                                           |
+| `push-builder-doc`                          | `--files <json> [--path <file.builder.mdx>] [--dryRun true\|false]`                                                                                                                                | Guarded Builder autosave PATCH for the safe Builder test model; never publishes                                                                                                   |
+| `navigate`                                  | `--path <path>` or `--documentId <id>` or `--databaseId <id>`                                                                                                                                      | Open a route, document page, or database page in the UI                                                                                                                           |
+| `search-documents`                          | `--query <text> [--format json]`                                                                                                                                                                   | Search by title/content and return snippets                                                                                                                                       |
+| `get-document`                              | `--id <id> [--format json]`                                                                                                                                                                        | Get a single document with content                                                                                                                                                |
+| `pull-document`                             | `--id <id> [--format markdown\|text]`                                                                                                                                                              | Collab-aware "ingest the final" read                                                                                                                                              |
+| `create-document`                           | `--title <text> [--content] [--parentId] [--icon]`                                                                                                                                                 | Create a new document                                                                                                                                                             |
+| `edit-document`                             | `--id <id> --find <text> --replace <text>`                                                                                                                                                         | Surgical text edit (preferred for modifications)                                                                                                                                  |
+| `edit-document`                             | `--id <id> --edits <json>`                                                                                                                                                                         | Batch surgical text edits                                                                                                                                                         |
+| `update-document`                           | `--id <id> [--title] [--content] [--icon]`                                                                                                                                                         | Full rewrite of document fields                                                                                                                                                   |
+| `share-local-file-document`                 | `--id <local-file-document-id>`                                                                                                                                                                    | Create or refresh a DB-backed shareable copy of a local file document                                                                                                             |
+| `remove-local-file-source`                  | `[--sourceRootPath <path>]`                                                                                                                                                                        | Unlink local-file sources from Content without deleting local Markdown/MDX files                                                                                                  |
+| `list-local-component-files`                |                                                                                                                                                                                                    | List registered local MDX component source files                                                                                                                                  |
+| `write-local-component-file`                | `--workspaceId <id> --path <relative-component-path> --content <source>`                                                                                                                           | Create or update a file in a registered local `components/` folder                                                                                                                |
+| `create-content-database`                   | `[--documentId <id>] [--parentId <id>] [--title <text>]`                                                                                                                                           | Create a database page or convert an existing page into a database                                                                                                                |
+| `create-inline-content-database`            | `--hostDocumentId <id> [--title <text>]`                                                                                                                                                           | Create a database owned by an inline database block in the host document                                                                                                          |
+| `get-content-database`                      | `--databaseId <id>` or `--documentId <id>`                                                                                                                                                         | Get a database table with property schema and item pages                                                                                                                          |
+| `list-trashed-content-databases`            |                                                                                                                                                                                                    | List soft-deleted databases visible in the sidebar Trash surface                                                                                                                  |
+| `restore-content-database`                  | `--databaseId <id>`                                                                                                                                                                                | Restore a soft-deleted database from the sidebar Trash surface                                                                                                                    |
+| `get-content-database-source`               | `--databaseId <id>` or `--documentId <id>`                                                                                                                                                         | Inspect local/no-source or source-backed status, mappings, row identity, freshness, and change sets                                                                               |
+| `attach-content-database-source`            | `--databaseId <id>` or `--documentId <id> [--sourceType mock-local\|builder-cms\|local-table\|notion-database] [--sourceName] [--sourceTable] [--relationshipMode items\|details] [--join <json>]` | Attach a source binding; use `items` to add more Builder rows and `details` to match a read-only local/Notion source onto existing rows                                           |
+| `list-notion-database-sources`              | `[--query <text>] [--limit <1-100>]`                                                                                                                                                               | List Notion data sources visible through the current user's OAuth connection; returns IDs/names only, never tokens                                                                |
+| `change-content-database-source-role`       | `--databaseId <id>` or `--documentId <id> --sourceId <id> --relationshipMode items\|details [--join <json>]`                                                                                       | Change an attached source between adding rows and adding matched detail columns without removing the source                                                                       |
+| `refresh-content-database-source`           | `--databaseId <id>` or `--documentId <id>`                                                                                                                                                         | Refresh the read-only source status envelope; large Builder CMS sources may return a partial fetch, and another refresh continues loading remaining rows                          |
+| `process-builder-body-hydration`            | `--sourceId <id> [--documentId <id>] [--limit <n>]`                                                                                                                                                | Hydrate queued Builder article bodies into readable Content markdown with preserved source-component markers                                                                      |
+| `set-content-database-source-write-mode`    | `--databaseId <id>` or `--documentId <id> --liveWritesEnabled true\|false [--allowedWriteModes <json>]`                                                                                            | Enable/disable per-source Builder live writes; enabling is allowed only for `agent-native-blog-article-test` with explicit modes                                                  |
+| `stage-builder-revision`                    | `--databaseId <id>` or `--documentId <id>`                                                                                                                                                         | Stage pending local Builder CMS changes as a local-only save-revision record; never calls Builder                                                                                 |
+| `review-content-database-source-change-set` | `--databaseId <id>` or `--documentId <id> --changeSetId <id> --decision approve\|reject [--note]`                                                                                                  | Approve or reject a local source change-set review record without provider writes                                                                                                 |
+| `stage-builder-source-bulk-update`          | `--databaseId <id>` or `--documentId <id> --itemIds <json-array>` or `--documentIds <json-array> --field <json> [--sourceId <id>] [--dryRun true\|false]`                                          | Preview or stage one bounded field update across selected source-backed Builder rows; apply still goes through Builder review/execution                                           |
+| `prepare-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--pushModeConfirmation autosave\|draft\|publish]`                                                                                    | Prepare a dry-run Builder execution gate for approved field/body changes with request semantics/idempotency key; never calls Builder                                              |
+| `validate-builder-source-execution`         | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>]`                                                                                                             | Validate/replay a prepared Builder execution gate locally as a dry run; never calls Builder                                                                                       |
+| `execute-builder-source-execution`          | `--databaseId <id>` or `--documentId <id> --changeSetId <id> [--idempotencyKey <key>] [--pushModeConfirmation autosave\|draft\|publish]`                                                           | Execute a guarded live Builder write only when approved, validated, enabled, idempotent, and targeting `agent-native-blog-article-test`                                           |
+| `add-database-item`                         | `--databaseId <id> [--title <text>] [--propertyValues <json>]`                                                                                                                                     | Add a page row to a database, optionally seeding property values                                                                                                                  |
+| `submit-content-database-form`              | `--databaseId <id> [--viewId <form-view-id>] [--title <text>] [--propertyValues <json>]`                                                                                                           | Submit one form response atomically; validates required questions, resolves option labels/IDs, writes Blocks correctly, verifies persistence, and returns the exact row page link |
+| `duplicate-database-item`                   | `--itemId <id>` or `--documentId <id> [--title <text>]`                                                                                                                                            | Duplicate exactly one database row page and its stored property values; for two or more rows, use `duplicate-database-items` once                                                 |
+| `duplicate-database-items`                  | `--databaseId <id>` or `--documentId <databaseDocumentId> --itemIds <json-array>` or `--documentIds <json-array>`                                                                                  | Preferred multi-row duplicate action; duplicate multiple database row pages atomically and return ordered duplicate item/document IDs                                             |
+| `delete-database-items`                     | `--databaseId <id>` or `--documentId <databaseDocumentId> --itemIds <json-array>` or `--documentIds <json-array>`                                                                                  | Preferred multi-row delete action; delete multiple database row pages atomically while preserving `delete-document` admin semantics                                               |
+| `move-database-item`                        | `--itemId <id>` or `--documentId <id> --position <number>`                                                                                                                                         | Move a database row page to a new zero-based table position                                                                                                                       |
+| `update-content-database-view`              | `--databaseId <id> --viewConfig <json>`                                                                                                                                                            | Persist database views, sorts, filters, hidden properties, and view settings                                                                                                      |
+| `list-document-properties`                  | `--documentId <id> [--format json]`                                                                                                                                                                | List Notion-style property definitions and values for a document                                                                                                                  |
+| `configure-document-property`               | `--documentId <id> [--id <propertyId>] --name <name> --type <type> [--visibility always_show\|hide_when_empty\|always_hide]`                                                                       | Create or update a property definition                                                                                                                                            |
+| `duplicate-document-property`               | `--documentId <id> --propertyId <propertyId>`                                                                                                                                                      | Duplicate a property definition and its stored values                                                                                                                             |
+| `delete-document-property`                  | `--documentId <id> --propertyId <propertyId>`                                                                                                                                                      | Delete a property definition and its stored values                                                                                                                                |
+| `set-document-property`                     | `--documentId <id> --propertyId <propertyId> --value <json>`                                                                                                                                       | Set a document property value (for a `blocks` field, the value is its markdown content)                                                                                           |
+| `reorder-document-property`                 | `--documentId <id> --propertyId <propertyId> --targetPropertyId <id> [--position before\|after]`                                                                                                   | Reorder a property definition within its database (used to reorder Blocks fields on the page)                                                                                     |
+| `set-document-discoverability`              | `--id <id> --hideFromSearch true\|false [--includeChildren true\|false]`                                                                                                                           | Hide/show an org-accessible document in Organization/search while keeping link access                                                                                             |
+| `move-document`                             | `--id <id> [--parentId] [--position]`                                                                                                                                                              | Move or reorder a document in the page tree                                                                                                                                       |
+| `delete-document`                           | `--id <id>`                                                                                                                                                                                        | Delete with recursive children                                                                                                                                                    |
 
 Database views follow Notion-style tab labels. When creating or duplicating
 views in `viewConfig`, use unique default names (`Table 2`, `SEO copy 2`, etc.)
@@ -295,20 +296,29 @@ explicit sync action.
 
 ### Notion Integration
 
-| Action                  | Args                                     | Purpose                                   |
-| ----------------------- | ---------------------------------------- | ----------------------------------------- |
-| `connect-notion-status` |                                          | Check Notion connection                   |
-| `link-notion-page`      | `--documentId <id> --pageId <id-or-url>` | Link doc to Notion page                   |
-| `list-notion-links`     |                                          | List linked documents                     |
-| `pull-notion-page`      | `--documentId <id>`                      | Pull content from Notion                  |
-| `push-notion-page`      | `--documentId <id>`                      | Push content to Notion                    |
-| `sync-notion-comments`  | `--documentId <id>`                      | Sync comments with Notion (bidirectional) |
+| Action                         | Args                                     | Purpose                                                               |
+| ------------------------------ | ---------------------------------------- | --------------------------------------------------------------------- |
+| `connect-notion-status`        |                                          | Check Notion connection                                               |
+| `link-notion-page`             | `--documentId <id> --pageId <id-or-url>` | Link doc to Notion page                                               |
+| `list-notion-links`            |                                          | List linked documents                                                 |
+| `pull-notion-page`             | `--documentId <id>`                      | Pull content from Notion                                              |
+| `push-notion-page`             | `--documentId <id>`                      | Push content to Notion                                                |
+| `sync-notion-comments`         | `--documentId <id>`                      | Sync comments with Notion (bidirectional)                             |
+| `list-notion-database-sources` | `[--query <text>] [--limit <n>]`         | List Notion databases available as read-only Content database sources |
 
 Use `provider-api-catalog`, `provider-api-docs`, and `provider-api-request`
 for Notion endpoints, filters, pagination modes, payload shapes, or API
 versions that these workflow actions do not model. Use `stageAs` plus
 `query-staged-dataset` for large Notion searches or database queries.
 
+Notion database sources are a bounded read-only pilot. Call
+`list-notion-database-sources`, choose the returned data-source ID, use
+`suggest-source-join-key`, then call `attach-content-database-source` with
+`sourceType: "notion-database"`, `relationshipMode: "details"`, and the
+confirmed canonical-key join. Refresh with `refresh-content-database-source`.
+Do not promise or attempt Notion database write-back; unsupported property
+types remain visible as read-only preservation markers.
+
 ### Comments
 
 Comments are Notion/Google-Docs-style **inline comments**. Selecting text and

package/corpus/templates/content/actions/_content-database-source-adapters.ts

@@ -0,0 +1,84 @@
+import type {
+  BuilderCmsModelFieldSummary,
+  ContentDatabaseSourceType,
+} from "../shared/api.js";
+import {
+  readBuilderCmsContentEntries,
+  readBuilderCmsModelFields,
+  type BuilderCmsReadProgress,
+  type BuilderCmsReadState,
+} from "./_builder-cms-read-client.js";
+import type { BuilderCmsSourceEntry } from "./_builder-cms-source-adapter.js";
+import { readLocalTableEntries } from "./_local-table-source.js";
+import { readNotionDatabaseSource } from "./_notion-database-source-adapter.js";
+
+export interface ContentDatabaseSourceReadResult {
+  state: BuilderCmsReadState;
+  entries: BuilderCmsSourceEntry[];
+  fields: BuilderCmsModelFieldSummary[];
+  fetchedAt: string;
+  message: string | null;
+  progress?: BuilderCmsReadProgress;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ContentDatabaseSourceAdapter {
+  sourceType: ContentDatabaseSourceType;
+  read(args: {
+    sourceTable: string;
+    limit: number;
+    offset: number;
+    fullRefresh?: boolean;
+  }): Promise<ContentDatabaseSourceReadResult>;
+}
+
+const builderCmsAdapter: ContentDatabaseSourceAdapter = {
+  sourceType: "builder-cms",
+  async read({ sourceTable, fullRefresh }) {
+    const fields = await readBuilderCmsModelFields({ model: sourceTable });
+    const read = await readBuilderCmsContentEntries({
+      model: sourceTable,
+      fieldPaths: fields.map((field) => `data.${field.name}`),
+      maxPages: fullRefresh ? undefined : 1,
+      limit: fullRefresh ? 10_000 : undefined,
+    });
+    return { ...read, fields };
+  },
+};
+
+const localTableAdapter: ContentDatabaseSourceAdapter = {
+  sourceType: "local-table",
+  async read({ sourceTable, limit, offset }) {
+    const { entries, modelFields: fields } = await readLocalTableEntries(
+      sourceTable,
+      { limit, offset },
+    );
+    return {
+      state: "live",
+      entries,
+      fields,
+      fetchedAt: new Date().toISOString(),
+      message: null,
+    };
+  },
+};
+
+const notionDatabaseAdapter: ContentDatabaseSourceAdapter = {
+  sourceType: "notion-database",
+  read: readNotionDatabaseSource,
+};
+
+const adapters = new Map<
+  ContentDatabaseSourceType,
+  ContentDatabaseSourceAdapter
+>(
+  [builderCmsAdapter, localTableAdapter, notionDatabaseAdapter].map(
+    (adapter) => [adapter.sourceType, adapter],
+  ),
+);
+
+export function getContentDatabaseSourceAdapter(
+  sourceType: ContentDatabaseSourceType,
+) {
+  return adapters.get(sourceType) ?? null;
+}