Merge pull request #195 from constructive-io/feat/view-docs-id-based-ownership

docs(data-modeling): correct view `data` to ID-based body + document ownership/AST validation

Author: pyramation

.agents/skills/constructive-access-control.zip

@@ -340,9 +340,12 @@ escape hatch, and combining predicates with expressions.
 ## Views
 
 Create views via `db.view.create`; `viewType` selects the view body (`View*` node
-type). Three optional options control PostgreSQL storage attributes and update
-semantics: `securityInvoker` (default `true`), `securityBarrier` (default
-`false`), and `checkOption` (`null | 'local' | 'cascaded'`).
+type). The body in `data` references its source by **catalog ID**
+(`source_table_id` / `field_ids`, etc.), never a raw schema/table name — the server
+resolves names and enforces same-database ownership + AST validation. Three optional
+options control PostgreSQL storage attributes and update semantics: `securityInvoker`
+(default `true`), `securityBarrier` (default `false`), and `checkOption`
+(`null | 'local' | 'cascaded'`).
 
 ```typescript
 await db.view.create({
@@ -352,7 +355,7 @@ await db.view.create({
     name: 'owners_view',
     viewType: 'ViewTableProjection',
     tableId: ownersTableId,
-    data: { source_schema: 'app_public', source_table: 'owners' },
+    data: { source_table_id: ownersTableId },
     securityBarrier: true,
     checkOption: 'cascaded',
     isReadOnly: false,
@@ -364,7 +367,8 @@ await db.view.create({
 //     SELECT ... WITH CASCADED CHECK OPTION
 ```
 
-See [views.md](./references/views.md) for all view options and generated SQL.
+See [views.md](./references/views.md) for all view options, the ID-based body, and
+ownership/validation guarantees.
 
 ## `api_required` (Required API Fields)
 

.agents/skills/constructive-agents.zip

@@ -7,6 +7,13 @@ each row compiles to a PostgreSQL `CREATE VIEW`. The view body is chosen by
 for the catalog: `ViewTableProjection`, `ViewJoinedTables`, `ViewAggregated`,
 `ViewFilteredTable`, `ViewComposite`).
 
+The view body lives in the `data` object and is **referenced by ID, never by raw
+schema/table name**. Depending on `viewType`, `data` carries `source_table_id` /
+`primary_table_id` / per-join `table_id` (all catalog table UUIDs) and optional
+`field_ids`. The server resolves each ID to the physical schema/table name for you
+and validates it (see [Referential integrity & ownership](#referential-integrity--ownership)),
+so you never hand-write a schema name into a view.
+
 ```typescript
 await db.view.create({
   data: {
@@ -15,7 +22,9 @@ await db.view.create({
     name: 'active_projects',
     viewType: 'ViewTableProjection',
     tableId: projectsTableId,
-    data: { source_schema: 'app_public', source_table: 'projects' },
+    // ID-based body: names are resolved from the catalog server-side.
+    // field_ids is optional — omit it to SELECT * from the source table.
+    data: { source_table_id: projectsTableId },
     isReadOnly: true,
   },
   select: { id: true },
@@ -49,7 +58,7 @@ await db.view.create({
     name: 'owners_view',
     viewType: 'ViewTableProjection',
     tableId: ownersTableId,
-    data: { source_schema: 'app_public', source_table: 'owners' },
+    data: { source_table_id: ownersTableId },
     securityInvoker: true,
     securityBarrier: true,
     checkOption: 'cascaded',
@@ -82,3 +91,28 @@ Set `checkOption: null` to drop the check option again.
 
 > Only `null | 'local' | 'cascaded'` are valid for `checkOption`. A check option
 > is meaningful only on updatable views (`isReadOnly: false`).
+
+## Referential integrity & ownership
+
+View bodies reference their source objects by **catalog ID** (`source_table_id`,
+`primary_table_id`, per-join `table_id`, `field_ids`) — never by a raw
+schema/table name you supply. This is what keeps views safe and tenant-scoped:
+
+- **Ownership is enforced.** Every referenced table ID is checked to belong to the
+  same `databaseId` as the view; a table from another database is rejected
+  (generates a `CROSS_DATABASE_REF` error). `field_ids` are likewise scoped to the
+  view's database. You cannot point a view at another tenant's table by ID or by
+  guessing its physical schema name.
+- **Names are derived, not trusted.** The physical `source_schema` / `source_table`
+  that end up in the generated `CREATE VIEW` are looked up from the ID server-side,
+  so a caller can't inject an arbitrary schema name.
+- **The query AST is validated.** Before the view is created/altered, the compiled
+  query is run through the same AST validator used by check constraints, indexes,
+  and functions — it restricts every referenced schema to the view's own database
+  schemas (plus framework schemas). This also covers the `ViewComposite` escape
+  hatch (`data.query_ast`): an out-of-scope schema reference there fails validation
+  rather than reaching PostgreSQL.
+
+So `db.view.create` gives the same ownership and AST-validation guarantees as the
+other declarative DDL surfaces — referencing by ID is the mechanism that provides
+them, which is why the name-based shortcut isn't accepted.