@@ -23,3 +23,17 @@ RPC 0.33.2 includes the scalar `DICT_INT16_UTF8` record fix required by macro an
 constraint metadata. Release qualification disables the composite source override
 and resolves that published dependency from Maven Central. No local repository
 fallback is part of the SDK build.
+
+## Constraints, nullability, generated columns and macros (vgi.v3)
+
+Constraints are canonical `ConstraintInfo` records the worker attests: build them with `ConstraintRecord.builder(schema, table, id)` (`notNull`, `primaryKey`, `unique`, `check`, `foreignKey`), state `ENFORCED` + `ALL_ROWS`, and attach them with `CatalogTable.Builder#constraints(records, revision)`. The pre-v3 `primaryKey`/`unique`/`check`/`foreignKeys` builders are `@Deprecated` and refused when the table is served. Every catalog path (main, auxiliary, hosted) advertises `vgi.constraint.records.read.v1` + `vgi.expression.duckdb.scalar.v1` and selects what the client offers automatically.
+
+Before serving a table the framework applies the rules DuckDB applies at ATTACH and refuses, naming the table, constraint id and column path: records owned by another table or a multi-component schema path, duplicate ids or declared names (case-insensitive), a second PRIMARY KEY, column paths that do not resolve (nested paths only on NOT_NULL, through ordinary STRUCTs), foreign keys to another schema, with an action other than NO_ACTION/RESTRICT or whose referenced key the catalog does not declare, and CHECK expressions outside the one-numeric-comparison grammar (`budget >= 0`: unqualified signed-integer/float columns and numeric literals).
+
+Nullability needs no author work: the served Arrow schema is rewritten so a field is non-nullable exactly when a NOT_NULL/PRIMARY_KEY record names it (descending through ordinary STRUCTs; the row-id column and logical-type storage are untouched). A non-nullable field no record names is served nullable.
+
+Generated columns: `CatalogColumns.virtualGenerated(name, type, sql, schemaPath)` builds a VIRTUAL column (nullable; BOOLEAN, signed integer or VARCHAR; the extension's deterministic scalar grammar, no division or float literals). Legacy `generated_expression` metadata is translated to that form when served.
+
+Capabilities: `CatalogProfiles` encodes, decodes and negotiates profiles (`negotiate`, `select`, `clientOffer`, `defaultClientOffer`). A hosted catalog that enforces constraints on its own write paths selects `vgi.constraint.create.v1` + `vgi.constraint.enforce.v1` from `CatalogInterface#catalogCapabilities`; only then does `CREATE TABLE` with constraint definitions reach its `tableCreate`. Auxiliary catalogs use `ExtraCatalog#withCapabilities`. `InMemoryCatalog` stores no rows and enforces nothing, so it refuses constrained, NOT NULL, logical-type and generated columns on `CREATE TABLE`.
+
+Macros: hosted catalogs build `MacroInfo` from a `Macro` descriptor with `MacroInfo.of(macro)`. Parameter defaults are literal values only (`NULL`, booleans, numbers, `'strings'`); an expression default such as `current_date` is refused by `registerMacro` at startup.
@@ -49,5 +49,5 @@ These build against `project(":vgi")` so they track the SDK at HEAD. A reader
 does the same thing with one line:
 
 ```kotlin
-implementation("farm.query:vgi:0.41.1")
+implementation("farm.query:vgi:0.45.1")
 ```
@@ -10,7 +10,7 @@
 // the SDK at HEAD and a breaking change shows up here rather than in a reader's
 // editor. A reader does the same thing with one line instead:
 //
-//     implementation("farm.query:vgi:0.44.0")
+//     implementation("farm.query:vgi:0.45.1")
 //
 // which is what the documentation shows. The toolchain, `-parameters` and the
 // JVM opens all come from the root build, so nothing else is repeated here.
 
@@ -209,14 +209,8 @@ private static byte[] wkb(String hex) {
     }
 
     /** Build a canonical VIRTUAL column owned by the data schema. */
-    private static Field genCol(String name,
-                ArrowType type,
-                boolean nullable,
-                String expr) {
-        return new Field(name,
-                new FieldType(nullable, type, null,
-                        Map.of("vgi.column.generated.v1", farm.query.vgi.internal.ColumnExpressions.generatedMetadata(expr, List.of("data")), "vgi.column.generation.v1", "virtual")),
-                null);
+    private static Field genCol(String name, ArrowType type, String expr) {
+        return farm.query.vgi.catalog.CatalogColumns.virtualGenerated(name, type, expr, List.of("data"));
     }
 
     /** STRUCT(xmin, ymin, xmax, ymax FLOAT) bbox column used by the native
@@ -1049,8 +1043,8 @@ private static void registerCatalogTables(Worker w) {
                 .registerCatalogTable(stubTable("data", "generated_sequence",
                         "Table with generated columns backed by sequence(10)",
                         col("n", Schemas.INT64, true),
-                        genCol("doubled", Schemas.INT64, true, "n * 2"),
-                        genCol("label", Schemas.UTF8, true, "'item_' || n::VARCHAR")))
+                        genCol("doubled", Schemas.INT64, "n * 2"),
+                        genCol("label", Schemas.UTF8, "'item_' || n::VARCHAR")))
                 .registerCatalogTable(stubTable("data", "projects",
                         "Projects with composite PK and FK to departments",
                         col("department_id", Schemas.INT64, false),
 
@@ -118,6 +118,25 @@ default List<String> catalogReadProfiles(byte[] attachId) {
         return List.of();
     }
 
+    /**
+     * This catalog's own capability advertisement and selection for an attach: build it with
+     * {@link CatalogProfiles#negotiate}. The framework merges in {@link #catalogReadProfiles},
+     * and gates the DDL it forwards on the selection: {@code CREATE TABLE} with constraint
+     * definitions reaches {@link #tableCreate} only when {@link CatalogProfiles#CONSTRAINT_CREATE},
+     * {@link CatalogProfiles#CONSTRAINT_ENFORCE} and {@link CatalogProfiles#CONSTRAINT_RECORDS_READ}
+     * were selected (DuckDB sends none otherwise). A catalog that selects them enforces every
+     * record it then serves, on every write path.
+     *
+     * <p>Default: no decision of its own.
+     *
+     * @param attachId the attach id
+     * @param request  the attach request (its {@code client_capabilities} is the client's offer)
+     * @return the decision; either side may be null
+     */
+    default Worker.CatalogCapabilitySelection catalogCapabilities(byte[] attachId, CatalogAttachRequest request) {
+        return new Worker.CatalogCapabilitySelection(null, null);
+    }
+
     /**
      * Release an attach. Default: nothing to release.
      *
@@ -177,7 +196,8 @@ default Optional<SchemaInfo> schema(byte[] attachId, List<String> path) {
     default List<ViewInfo> views(byte[] attachId, List<String> path) { return List.of(); }
 
     /**
-     * The macros of a schema of one type. Default: none.
+     * The macros of a schema of one type. Default: none. Build each family from a simple
+     * descriptor with {@link MacroInfo#of(farm.query.vgi.catalog.Macro)}.
      *
      * @param attachId the attach id
      * @param path     the schema path
@@ -280,7 +300,27 @@ default void tableDrop(byte[] attachId, List<String> path, String name, boolean
     }
 
     /**
-     * {@code CREATE VIEW}. Default: read-only.
+     * {@code CREATE VIEW}, as vgi 0.44 declared it. Default: read-only.
+     *
+     * @param attachId   the attach id
+     * @param path       the schema path
+     * @param name       the view name
+     * @param definition the view's SQL
+     * @param onConflict what to do when it exists
+     * @deprecated override {@link #viewCreate(byte[], List, String, String, OnConflict, List)}
+     *             (column aliases) or the full form (comment, tags, column comments); an
+     *             override of this one is still reached for a view that uses none of them.
+     */
+    @Deprecated
+    default void viewCreate(byte[] attachId, List<String> path, String name, String definition,
+                            OnConflict onConflict) {
+        throw readOnly("catalog_view_create");
+    }
+
+    /**
+     * {@code CREATE VIEW} with optional column aliases. Default: the 5-argument form when there
+     * are no aliases; with aliases, refused as read-only (or, when only the 5-argument form is
+     * overridden, as unsupported, rather than dropping them).
      *
      * @param attach     the attach id
      * @param path       the schema path
@@ -289,13 +329,48 @@ default void tableDrop(byte[] attachId, List<String> path, String name, boolean
      * @param conflict   what to do when it exists
      * @param aliases    optional view column aliases
      */
-    default void viewCreate(byte[] attach, List<String> path, String name, String definition, OnConflict conflict, List<String> aliases) {
-        viewCreate(attach, path, name, definition, conflict, aliases, null, null, null);
+    @SuppressWarnings("deprecation")
+    default void viewCreate(byte[] attach, List<String> path, String name, String definition, OnConflict conflict,
+                            List<String> aliases) {
+        if (aliases == null || aliases.isEmpty()) {
+            viewCreate(attach, path, name, definition, conflict);
+            return;
+        }
+        if (overrides("viewCreate", byte[].class, List.class, String.class, String.class, OnConflict.class)) {
+            throw new UnsupportedOperationException("catalog " + name() + " does not support view column aliases:"
+                    + " override viewCreate(attachId, path, name, definition, onConflict, aliases)");
+        }
+        throw readOnly("catalog_view_create");
     }
 
+    /**
+     * {@code CREATE VIEW} with every option; the framework calls this one. Default: the
+     * 6-argument form when there is no comment, tag or column comment; otherwise refused as
+     * read-only (or, when a shorter form is overridden, as unsupported, rather than dropping them).
+     *
+     * @param attachId       the attach id
+     * @param path           the schema path
+     * @param name           the view name
+     * @param definition     the view's SQL
+     * @param onConflict     what to do when it exists
+     * @param aliases        optional view column aliases
+     * @param comment        the view comment, or {@code null}
+     * @param tags           view tags, or {@code null}
+     * @param columnComments per-output-column comments, or {@code null}
+     */
     default void viewCreate(byte[] attachId, List<String> path, String name, String definition,
                             OnConflict onConflict, List<String> aliases, String comment,
                             Map<String, String> tags, Map<String, String> columnComments) {
+        if (comment == null && (tags == null || tags.isEmpty()) && (columnComments == null || columnComments.isEmpty())) {
+            viewCreate(attachId, path, name, definition, onConflict, aliases == null ? List.of() : aliases);
+            return;
+        }
+        if (overrides("viewCreate", byte[].class, List.class, String.class, String.class, OnConflict.class, List.class)
+                || overrides("viewCreate", byte[].class, List.class, String.class, String.class, OnConflict.class)) {
+            throw new UnsupportedOperationException("catalog " + name() + " does not support view comments or tags:"
+                    + " override viewCreate(attachId, path, name, definition, onConflict, aliases, comment, tags,"
+                    + " columnComments)");
+        }
         throw readOnly("catalog_view_create");
     }
 
@@ -356,6 +431,15 @@ private UnsupportedOperationException readOnly(String method) {
                 "catalog " + name() + " is read-only: " + method + " not supported");
     }
 
+    /** Whether this catalog's class overrides the named default method. */
+    private boolean overrides(String method, Class<?>... parameters) {
+        try {
+            return getClass().getMethod(method, parameters).getDeclaringClass() != CatalogInterface.class;
+        } catch (NoSuchMethodException e) {
+            return false;
+        }
+    }
+
     /**
      * Schema paths compare case-insensitively, as DuckDB identifiers do.
      *