From feeeec878f41c6dd5e26e27dfc92a1ccfe67506d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 2 Sep 2026 15:15:52 +0000
Subject: [PATCH] docs(configure): federation ships today, and
 defineDatasource() exists
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`configure/data-sources.mdx` told readers that in-product external
datasource federation was a roadmap item and that no `defineDatasource()`
helper existed. Both claims are stale at the source:

- All four "planned, not yet shipped" bullets are shipped on objectstack
  `origin/main` (`SchemaModeSchema`, `external` on `ObjectSchema`, the
  `datasource/{introspect,validate,list-tables}` CLI, the boot/write gates
  and the runtime Sync wizard — ADR-0062 R1/R5c/R6/R7).
- ADR-0015's own status line reads "Accepted", not "Proposed".
- `export function defineDatasource` is live in
  `packages/spec/src/data/datasource.zod.ts` and re-exported from both
  `@objectstack/spec` and `@objectstack/spec/data`.

The Roadmap section becomes a short pointer to the framework guide that
owns this surface rather than a second description of it — the mirror
follows, it does not lead. The `defineDatasource()` note names the helper
as available without implying the plain-object form stopped working; it
has not.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ChPQM8jamxLUfUAxwFpJ8S
---
 content/docs/configure/data-sources.mdx | 36 +++++++++++--------------
 1 file changed, 16 insertions(+), 20 deletions(-)

diff --git a/content/docs/configure/data-sources.mdx b/content/docs/configure/data-sources.mdx
index 20a06f8..40c6d68 100644
--- a/content/docs/configure/data-sources.mdx
+++ b/content/docs/configure/data-sources.mdx
@@ -85,9 +85,14 @@ export default defineStack({
 });
 ```
 
-> There is **no** `defineDatasource()` helper. A datasource is just a
-> `Datasource` object you place in the `datasources` array — exactly like
-> the `examples/app-crm` stack does in the framework repo.
+> **A `defineDatasource()` helper is also available.** The plain
+> `Datasource` object above is a valid datasource — it is exactly what the
+> `examples/app-crm` stack does in the framework repo — and
+> `defineDatasource()`, exported from `@objectstack/spec` (and
+> `@objectstack/spec/data`), takes the same config and runs the
+> `DatasourceSchema` validation at the point of declaration, so a bad field
+> is reported where you wrote it. The framework's own federation guide uses
+> it.
 
 ## Binding objects to a datasource
 
@@ -229,26 +234,17 @@ configuration that backs the `default` datasource.
 - **Scope with permissions.** Object- and field-level permissions apply
   to connected data exactly as they do to native objects.
 
-## Roadmap: in-product External Datasource Federation
+## In-product external datasource federation
 
 The flow above — connect a database, model objects, generate them with a
-coding agent — works today with shipped building blocks. A richer,
-**turn-key federation** experience is in active design under
+coding agent — is the general path. The **turn-key federation** flow on top
+of it, specified in
 [ADR-0015](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0015-external-datasource-federation.md)
-(status: *Proposed*). Planned, **not yet shipped**:
-
-- A `schemaMode` (`managed` / `external` / `validate-only`) so ObjectOS
-  can bind to tables it does **not** own without trying to migrate them.
-- An `external` binding sub-record on objects mapping object fields to
-  existing columns.
-- An `os datasource introspect` / `validate` CLI to import a schema and
-  scaffold objects in one step.
-- Boot-time and write-time **safety gates** for externally-owned schemas,
-  plus a Studio wizard for the whole flow.
-
-Until those land, prefer the documented path: declare the datasource,
-bind objects (generated or hand-written), and verify against a
-non-production copy first.
+(status: *Accepted*), **ships today**: bind objects to tables ObjectOS does
+not own, with validation gates around them.
+
+It is documented once, with the framework docs that own the surface —
+[External Datasources (Federation)](https://docs.objectstack.ai/docs/data-modeling/external-datasources).
 
 ## Where to go next