@quereus/quereus 3.3.0 → 4.1.0

package/dist/src/func/builtins/schema.js

@@ -3,11 +3,20 @@ import { QuereusError } from "../../common/errors.js";
 import { StatusCode } from "../../common/types.js";
 import { isScalarFunctionSchema, isTableValuedFunctionSchema, isAggregateFunctionSchema } from "../../schema/function.js";
 import { isWindowFunction } from "../../schema/window-function.js";
+import { exposedImplicitIndexes } from "../../schema/catalog.js";
+import { isMaintainedTable } from "../../schema/derivation.js";
+import { generateMaintainedTableDDL } from "../../schema/ddl-generator.js";
 import { INTEGER_TYPE, TEXT_TYPE } from "../../types/builtin-types.js";
 import { FunctionFlags } from "../../common/constants.js";
 import { RowOpFlag } from "../../schema/table.js";
 import { jsonStringify } from "../../util/serialization.js";
 import { expressionToString } from "../../emit/ast-stringify.js";
+import { createLogger } from "../../common/logger.js";
+import { TableReferenceNode } from "../../planner/nodes/reference.js";
+import { isJoinBody, isDecomposableJoinBody } from "../../planner/mutation/multi-source.js";
+import { isSetOpMembershipBody, isSetOpBranchWritable, setOpHasSubtreeOperand, setOpJoinLegsInsertable, surfacedInnerFlagNames, isSetOpFlaglessWritableBody, flaglessDiscriminatorColumnNames } from "../../planner/mutation/set-op.js";
+import { bodyDefaults } from "../../schema/view.js";
+const log = createLogger('func:view_info');
 /**
  * Encodes a tag bag as a JSON object string. Returns null when there are no
  * tags so callers can use `WHERE tags IS NULL` to filter untagged objects.
@@ -21,6 +30,31 @@ function tagsToJson(tags) {
         return null;
     return jsonStringify(tags);
 }
+/**
+ * Builds the `CREATE INDEX "name" ON "table" (cols)` string a `schema()` row
+ * surfaces. Shared by real `IndexSchema` rows and synthetic exposed-implicit
+ * descriptors (both expose `name` + `columns`). Returns `null` if a referenced
+ * column index is out of range, matching the prior inline behavior.
+ */
+function buildIndexCreateSql(index, tableSchema) {
+    try {
+        const indexColumns = index.columns.map(col => {
+            const column = tableSchema.columns[col.index];
+            let colStr = `"${column.name}"`;
+            if (col.collation) {
+                colStr += ` COLLATE ${col.collation}`;
+            }
+            if (col.desc) {
+                colStr += ' DESC';
+            }
+            return colStr;
+        }).join(', ');
+        return `CREATE INDEX "${index.name}" ON "${tableSchema.name}" (${indexColumns})`;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Converts a RowOpMask bitmask to a comma-joined operations list.
  * An empty/default mask returns the canonical default-all string so the
@@ -76,16 +110,23 @@ export const schemaFunc = createIntegratedTableValuedFunction({
             for (const tableSchema of schemaInstance.getAllTables()) {
                 let createSql = null;
                 try {
-                    const columnsStr = tableSchema.columns.map((c) => `"${c.name}" ${c.logicalType.name}`).join(', ');
-                    const argsStr = Object.entries(tableSchema.vtabArgs ?? {}).map(([key, value]) => `${key}=${value}`).join(', ');
-                    createSql = `create table "${tableSchema.name}" (${columnsStr}) using ${tableSchema.vtabModuleName}(${argsStr})`;
+                    if (isMaintainedTable(tableSchema)) {
+                        // A maintained table (materialized view) lists exactly ONCE,
+                        // as itself, with its canonical create-materialized-view DDL.
+                        createSql = generateMaintainedTableDDL(tableSchema);
+                    }
+                    else {
+                        const columnsStr = tableSchema.columns.map((c) => `"${c.name}" ${c.logicalType.name}`).join(', ');
+                        const argsStr = Object.entries(tableSchema.vtabArgs ?? {}).map(([key, value]) => `${key}=${value}`).join(', ');
+                        createSql = `create table "${tableSchema.name}" (${columnsStr}) using ${tableSchema.vtabModuleName}(${argsStr})`;
+                    }
                 }
                 catch {
                     createSql = null;
                 }
                 yield [
                     schemaName,
-                    tableSchema.isView ? 'view' : 'table',
+                    tableSchema.isView ? 'view' : isMaintainedTable(tableSchema) ? 'materialized_view' : 'table',
                     tableSchema.name,
                     tableSchema.name,
                     createSql,
@@ -94,34 +135,30 @@ export const schemaFunc = createIntegratedTableValuedFunction({
                 // Process Indexes for this table
                 if (tableSchema.indexes) {
                     for (const indexSchema of tableSchema.indexes) {
-                        let indexSql = null;
-                        try {
-                            const indexColumns = indexSchema.columns.map(col => {
-                                const column = tableSchema.columns[col.index];
-                                let colStr = `"${column.name}"`;
-                                if (col.collation) {
-                                    colStr += ` COLLATE ${col.collation}`;
-                                }
-                                if (col.desc) {
-                                    colStr += ' DESC';
-                                }
-                                return colStr;
-                            }).join(', ');
-                            indexSql = `CREATE INDEX "${indexSchema.name}" ON "${tableSchema.name}" (${indexColumns})`;
-                        }
-                        catch {
-                            indexSql = null;
-                        }
                         yield [
                             schemaName,
                             'index',
                             indexSchema.name,
                             tableSchema.name,
-                            indexSql,
+                            buildIndexCreateSql(indexSchema, tableSchema),
                             tagsToJson(indexSchema.tags)
                         ];
                     }
                 }
+                // Surface exposed implicit covering indexes the backend did NOT
+                // materialize as `IndexSchema` entries (store mode). In memory mode
+                // `exposedImplicitIndexes` returns [] (the name is already in
+                // `tableSchema.indexes` above), so this loop is a no-op there.
+                for (const desc of exposedImplicitIndexes(tableSchema)) {
+                    yield [
+                        schemaName,
+                        'index',
+                        desc.name,
+                        tableSchema.name,
+                        buildIndexCreateSql(desc, tableSchema),
+                        tagsToJson(desc.tags)
+                    ];
+                }
             }
             // Process Views
             for (const viewSchema of schemaInstance.getAllViews()) {
@@ -134,8 +171,10 @@ export const schemaFunc = createIntegratedTableValuedFunction({
                     tagsToJson(viewSchema.tags)
                 ];
             }
-            // Process Functions
+            // Process Functions (skip hidden internal helpers)
             for (const funcSchema of schemaInstance._getAllFunctions()) {
+                if (funcSchema.hidden)
+                    continue;
                 yield [
                     schemaName,
                     'function',
@@ -326,11 +365,19 @@ export const indexInfoFunc = createIntegratedTableValuedFunction({
     if (!table) {
         throw new QuereusError(`Table '${tableName}' not found`, StatusCode.ERROR);
     }
-    if (!table.indexes)
+    // Real indexes plus any exposed implicit covering index the backend did NOT
+    // materialize as an `IndexSchema` (store mode). In memory mode the second
+    // list is empty (the name already lives in `table.indexes`), so the row set
+    // matches across backends. Synthetic descriptors carry no `unique` flag —
+    // UNIQUE enforcement routes through `uniqueConstraints` — so they report
+    // `unique = 0`, mirroring the memory materialized entry.
+    const realIndexes = table.indexes ?? [];
+    const synthetic = exposedImplicitIndexes(table);
+    if (realIndexes.length === 0 && synthetic.length === 0)
         return;
-    for (const idx of table.indexes) {
+    for (const idx of [...realIndexes, ...synthetic]) {
         const tagJson = tagsToJson(idx.tags);
-        const uniqueFlag = idx.unique ? 1 : 0;
+        const uniqueFlag = ('unique' in idx && idx.unique) ? 1 : 0;
         const partialFlag = idx.predicate ? 1 : 0;
         for (let seq = 0; seq < idx.columns.length; seq++) {
             const col = idx.columns[seq];
@@ -548,4 +595,646 @@ export const functionInfoFunc = createIntegratedTableValuedFunction({
         yield ['error', -1, 'error', 0, 0, `Failed to get function info: ${error.message}`];
     }
 });
+/** The conservative all-`NO` / `[]` row for a body with no recoverable base lineage. */
+const CONSERVATIVE_VIEW_INFO = {
+    isInsertableInto: false,
+    isUpdatable: false,
+    isDeletable: false,
+    effectiveTargets: [],
+};
+/** SQL-standard `'YES'`/`'NO'` text encoding for a boolean updateability flag. */
+function yesNo(value) {
+    return value ? 'YES' : 'NO';
+}
+/**
+ * Resolve an UpdateSite to its underlying base reference: the producing
+ * `TableReferenceNode` id + base column for a `base` site (plain or `null-extended`),
+ * else `undefined` (a `computed` / leaf-less site). `nullExtended` is true when an
+ * outer-join `null-extended` layer was unwrapped to reach the base — the column names a
+ * base table/column (so it is insertable through the both-sides envelope and counts as
+ * an effective target) but is read-only on UPDATE (the deferred per-row materialization),
+ * so the per-column / `is_updatable` surfaces report it non-updatable.
+ */
+function baseSiteOf(site) {
+    let s = site;
+    let nullExtended = false;
+    while (s && s.kind === 'null-extended') {
+        nullExtended = true;
+        s = s.inner;
+    }
+    return s && s.kind === 'base' ? { table: s.table, baseColumn: s.baseColumn, nullExtended } : undefined;
+}
+/** Every relational node in the planned body (deduped), root-first. */
+function collectBodyNodes(root) {
+    const out = [];
+    const seen = new Set();
+    const visit = (n) => {
+        if (seen.has(n))
+            return;
+        seen.add(n);
+        out.push(n);
+        for (const child of n.getRelations())
+            visit(child);
+    };
+    visit(root);
+    return out;
+}
+/**
+ * Index every `TableReferenceNode` in a planned body by its numeric node id.
+ * Shared by `deriveViewInfo` and `deriveColumnInfo`: an UpdateSite's `table`
+ * field is the producing reference's id, which both surfaces resolve back to a
+ * base-table name through this map.
+ */
+function buildTableRefsById(nodes) {
+    const tableRefsById = new Map();
+    for (const n of nodes) {
+        if (n instanceof TableReferenceNode)
+            tableRefsById.set(Number(n.id), n);
+    }
+    return tableRefsById;
+}
+/** Record `baseColumn` (lowercased) as defaultable for base table `table`. */
+function addDefaultable(map, table, baseColumn) {
+    const set = map.get(table) ?? new Set();
+    set.add(baseColumn.toLowerCase());
+    map.set(table, set);
+}
+/**
+ * Derive the four view-level updateability columns statically from the planned
+ * view body. The **logical** tree is used deliberately (via `_buildPlan`, not
+ * `getPlan`): it preserves the Project/Filter/Join/TableReference operator
+ * structure that threads `updateLineage`, whereas the optimizer degrades a join's
+ * top-node lineage to `computed` (docs/view-updateability.md § surface authority).
+ * This mirrors the view-mutation substrate (`planner/mutation/*`), which plans the
+ * body logically for the same reason — so `effective_targets` agrees with the
+ * base set `propagate()` reaches.
+ *
+ * Re-plans on every call (same re-plan-on-read posture as `deriveBackingShape`);
+ * caching is a later optimization.
+ */
+function deriveViewInfo(db, view) {
+    const { plan } = db._buildPlan([view.selectAst]);
+    const root = plan.getRelations()[0];
+    if (!root)
+        return CONSERVATIVE_VIEW_INFO;
+    const nodes = collectBodyNodes(root);
+    // The minimal `MutableViewLike` the set-op insertability probe re-derives the branches from
+    // (the same `{ name, schemaName, selectAst }` shape the write path / `deriveBackingShape` use).
+    const viewAsMutable = { name: view.name, schemaName: view.schemaName, selectAst: view.selectAst };
+    // Set-operation membership body: the per-branch fan-out makes the view
+    // insertable-into (flag-routed insert-through), updatable (membership flip + data
+    // fan-out), and deletable (delete fan-out), agreeing with the dynamic `propagate()`
+    // truth (`set-op-membership-write`). The effective targets are the branch base
+    // tables. A plain (flag-less) set-op body is NOT this case — it falls through to the
+    // `targetIds.size === 0` conservative row below (no membership column to address a branch).
+    if (isSetOpMembershipBody(view.selectAst)) {
+        // Branch-writability shape gate (mirrors the non-decomposable join shape gate below):
+        // a membership body the dynamic write (`analyzeSetOpView`) would reject — an outer
+        // LIMIT/OFFSET (non-decomposable window), a non-SELECT right operand, a `select *`
+        // leg, a computed leg, or legs with mismatched column counts — is gated out here.
+        // Without this gate the
+        // surface would over-claim writable from the membership flag's presence alone; report
+        // the conservative all-`NO` row to agree with the dynamic `propagate()` reject.
+        if (!isSetOpBranchWritable(view.selectAst))
+            return CONSERVATIVE_VIEW_INFO;
+        const targets = [...new Set([...buildTableRefsById(nodes).values()].map(r => r.tableSchema.name))].sort();
+        // Update / delete fan-out recurses through a subtree operand to its member leaves
+        // (`nestable-flagged-set-ops`) AND composes a multi-source (INNER join) branch
+        // (`set-op-write-multisource-leg-compose`), so updatable / deletable stay YES at any depth.
+        // Insert through a join branch is now SHIPPED via the nested shared-surrogate envelope splice
+        // (`set-op-write-multisource-leg-insert`), so `is_insertable_into` is YES for a body whose
+        // join branches are ALL insertable — re-derived dynamically by `setOpJoinLegsInsertable`
+        // (NO for a composite-key / no-default / non-equi join branch). It stays NO when EITHER
+        // operand is a subtree: inserting into a multi-leaf subtree has no single deterministic
+        // target leaf (product-coordinate addressing — `set-op-membership-nested`).
+        const isInsertableInto = !setOpHasSubtreeOperand(view.selectAst)
+            && setOpJoinLegsInsertable(db._buildProbeContext(), viewAsMutable);
+        return { isInsertableInto, isUpdatable: true, isDeletable: true, effectiveTargets: targets };
+    }
+    // Flag-less predicate-honest set-op body (`set-op-flagless-predicate-honest-writes`): a
+    // flag-less body of literal-discriminator legs is insertable (routed to the consistent
+    // legs), updatable (data-column fan-out; the literal discriminators are read-only), and
+    // deletable (fan-out) — agreeing with the dynamic `buildFlaglessSetOpWrite` truth. The
+    // recognizer is the static shadow of the dynamic write's shape acceptance (it admits
+    // literal projections, unlike the membership probe), so a body it rejects (outer
+    // LIMIT/OFFSET, `select *` / computed leg, deep intersect/except) falls through to the
+    // `targetIds.size === 0` conservative row below.
+    if (isSetOpFlaglessWritableBody(view.selectAst)) {
+        const targets = [...new Set([...buildTableRefsById(nodes).values()].map(r => r.tableSchema.name))].sort();
+        // Insert through a multi-source (join) leg is now SHIPPED via the nested shared-surrogate
+        // envelope splice (`set-op-write-multisource-leg-insert`), so `is_insertable_into` is YES for
+        // a body whose join legs are ALL insertable — re-derived dynamically by
+        // `setOpJoinLegsInsertable` (NO for a composite-key / no-default / non-equi join leg) —
+        // matching the dynamic `buildFlaglessInsert`; UPDATE / DELETE through the join leg stay YES.
+        const isInsertableInto = setOpJoinLegsInsertable(db._buildProbeContext(), viewAsMutable);
+        return { isInsertableInto, isUpdatable: true, isDeletable: true, effectiveTargets: targets };
+    }
+    // Non-decomposable join shape gate: cross / comma (implicit) / subquery- or
+    // function-source join bodies are not write-through-able, so they must report the
+    // conservative all-`NO` row. `propagate()` decomposes an n-way (≥2) equi-join —
+    // `inner`/`left`/`right`/`full` (RIGHT now admitted, the LEFT mirror; FULL self-conservatizes), composite-PK
+    // sides and self-joins included
+    // (`isDecomposableJoinBody`, the boolean shadow of `collectJoinSources`) — and rejects
+    // every other join shape, so without this gate the target walk below would resolve
+    // their bases and over-report `is_updatable = 'YES'`. Outer joins ARE decomposable
+    // now (partially writable), so they flow through to the per-column walk, which reports
+    // a non-preserved (`null-extended`) column non-updatable via `baseSiteOf().nullExtended`
+    // — agreeing with the dynamic `propagate()` truth (a non-preserved update rejects).
+    if (isJoinBody(view.selectAst) && !isDecomposableJoinBody(view.selectAst)) {
+        return CONSERVATIVE_VIEW_INFO;
+    }
+    const tableRefsById = buildTableRefsById(nodes);
+    // Output-column lineage: effective targets, the per-table set of base columns
+    // exposed by the projection, and the is_updatable flag (≥1 output column with a
+    // PRESERVED base site — a non-preserved `null-extended` column is read-only on
+    // update, so it does not make the view updatable). `preservedTargets` are the base
+    // tables a column reaches non-null-extended — the only ones a DELETE routes to
+    // (§ Outer Joins — Deletes), so they alone gate deletability below.
+    const rootLineage = root.physical?.updateLineage;
+    const targetIds = new Set();
+    const preservedTargets = new Set();
+    const exposed = new Map();
+    let anyBase = false;
+    for (const attr of root.getAttributes()) {
+        const site = rootLineage?.get(attr.id);
+        // An authored (`with inverse`) column exposes each put's target base column —
+        // it is writable through the put expressions, so the targets count toward base
+        // reachability exactly like identity columns. INSERT coverage (`exposed`) is
+        // counted only for a single-source body: the single-source spine evaluates the
+        // puts per supplied row, but the multi-source insert envelope defers authored
+        // puts, so counting them there would over-report `is_insertable_into`.
+        if (site?.kind === 'authored') {
+            for (const put of site.puts) {
+                anyBase = true;
+                preservedTargets.add(put.table);
+                targetIds.add(put.table);
+                if (!isJoinBody(view.selectAst)) {
+                    const set = exposed.get(put.table) ?? new Set();
+                    set.add(put.baseColumn.toLowerCase());
+                    exposed.set(put.table, set);
+                }
+            }
+            continue;
+        }
+        const bs = baseSiteOf(site);
+        if (!bs)
+            continue;
+        if (!bs.nullExtended) {
+            anyBase = true;
+            preservedTargets.add(bs.table);
+        }
+        targetIds.add(bs.table);
+        // A null-extended column still exposes its base column for INSERT coverage (the
+        // both-sides envelope supplies it) — add it regardless of preservation.
+        const set = exposed.get(bs.table) ?? new Set();
+        set.add(bs.baseColumn.toLowerCase());
+        exposed.set(bs.table, set);
+    }
+    // No base lineage at the root ⇒ wholly read-only (VALUES / aggregate / set-op /
+    // computed-only / recursive-CTE body). The conservative row falls straight out.
+    if (targetIds.size === 0)
+        return CONSERVATIVE_VIEW_INFO;
+    // No PRESERVED base column ⇒ a FULL outer join (every side null-extended), or a
+    // LEFT/RIGHT body that projects away its whole preserved side. v1 defers write-through
+    // there (a full-outer write is per-row — § Outer Joins; a RIGHT body now reaches here
+    // but always has a preserved anchor), so report the conservative
+    // row, agreeing with the dynamic rejects (`unsupported-outer-join-update` on update,
+    // `unsupported-join` on delete/insert through a side-less preserved set).
+    if (preservedTargets.size === 0)
+        return CONSERVATIVE_VIEW_INFO;
+    // Defaultable base columns: every (node, attribute) carrying an insert default
+    // (`constant-fd` selection pin, declared `base-default`, `view-insert-default`),
+    // resolved through THAT node's own lineage back to a base column. Walking the
+    // whole spine — not just the root — recovers a *projected-away* constant-FD
+    // column (e.g. `select name from t where color = 'green'`, where `color`'s
+    // default lives on the Filter, below the projection that drops it).
+    const defaultable = new Map();
+    for (const n of nodes) {
+        const nl = n.physical?.updateLineage;
+        const nd = n.physical?.attributeDefaults;
+        if (!nl || !nd)
+            continue;
+        for (const attrId of nd.keys()) {
+            const bs = baseSiteOf(nl.get(attrId));
+            if (!bs)
+                continue;
+            addDefaultable(defaultable, bs.table, bs.baseColumn);
+        }
+    }
+    // View-level insert defaults (Divergence 1): the `view-insert-default`
+    // provenance is never threaded onto `PhysicalProperties` (it is consumed only
+    // in the rewrite), so this body is planned without the view's defaults and the
+    // walk above misses them. Fold each `with defaults (col = expr, …)` clause
+    // column (now stored on the body select AST) into `defaultable` directly,
+    // mirroring `resolveDefaultForColumn` — a base column of a reachable target
+    // (the common projected-away case) or a visible view-output column with base
+    // lineage. Unlike the rewrite, an unresolvable name is silently skipped: a
+    // read-only introspection surface stays on its never-throw posture (the
+    // per-view try/catch would otherwise collapse the row to all-`NO`).
+    const defaultedColumns = new Set((bodyDefaults(view.selectAst) ?? []).map(d => d.column.toLowerCase()));
+    for (const colName of defaultedColumns) {
+        let resolved = false;
+        for (const id of targetIds) {
+            const match = tableRefsById.get(id)?.tableSchema.columns
+                .find(c => c.name.toLowerCase() === colName);
+            if (match) {
+                addDefaultable(defaultable, id, match.name);
+                resolved = true;
+            }
+        }
+        if (resolved)
+            continue;
+        const attr = root.getAttributes().find(a => a.name.toLowerCase() === colName);
+        const bs = attr && baseSiteOf(rootLineage?.get(attr.id));
+        if (bs)
+            addDefaultable(defaultable, bs.table, bs.baseColumn);
+    }
+    const targetNames = new Set();
+    let isDeletable = true;
+    let isInsertableInto = true;
+    for (const id of targetIds) {
+        const ref = tableRefsById.get(id);
+        if (!ref) {
+            // A base-site id with no resolved TableReferenceNode should not happen
+            // (root lineage ids come from the nodes we collected); fail conservative.
+            isDeletable = false;
+            isInsertableInto = false;
+            continue;
+        }
+        const tbl = ref.tableSchema;
+        targetNames.add(tbl.name);
+        const exp = exposed.get(id) ?? new Set();
+        const def = defaultable.get(id) ?? new Set();
+        // Deletability + insertability are decided over the PRESERVED targets only — a
+        // non-preserved (outer-join) target is never the delete route (deleting it merely
+        // null-extends the row — § Outer Joins — Deletes) and is an *optional* member of
+        // the insert fan-out (the preserved-only insert omits it). So a non-preserved
+        // target's unexposed PK / uncovered not-null column does not block either flag; a
+        // real both-sides insert that DOES supply it is gated at runtime instead.
+        if (!preservedTargets.has(id))
+            continue;
+        // Deletable iff every preserved target's PK is exposed through base lineage (so
+        // `pk = <view value>` is constructible). A keyless preserved base is undeletable.
+        const pkCols = tbl.primaryKeyDefinition.map(pk => tbl.columns[pk.index].name.toLowerCase());
+        if (pkCols.length === 0 || !pkCols.every(c => exp.has(c)))
+            isDeletable = false;
+        // Insertable iff every not-null-without-declared-default, non-generated base
+        // column has a recoverable value: projected (exposed) or carries an insert
+        // default. Generated columns are computed/auto; nullable columns take null;
+        // declared-default columns supply themselves.
+        for (const col of tbl.columns) {
+            if (col.generated || !col.notNull || col.defaultValue != null)
+                continue;
+            const name = col.name.toLowerCase();
+            if (!exp.has(name) && !def.has(name)) {
+                isInsertableInto = false;
+                break;
+            }
+        }
+    }
+    return {
+        isInsertableInto,
+        isUpdatable: anyBase,
+        isDeletable,
+        effectiveTargets: [...targetNames].sort(),
+    };
+}
+// View updateability function (table-valued function)
+export const viewInfoFunc = createIntegratedTableValuedFunction({
+    name: 'view_info',
+    numArgs: -1,
+    deterministic: false, // Schema (and therefore lineage) can change
+    returnType: {
+        typeClass: 'relation',
+        isReadOnly: true,
+        isSet: false,
+        columns: [
+            { name: 'schema', type: { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: false, isReadOnly: true }, generated: true },
+            { name: 'name', type: { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: false, isReadOnly: true }, generated: true },
+            { name: 'is_insertable_into', type: { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: false, isReadOnly: true }, generated: true },
+            { name: 'is_updatable', type: { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: false, isReadOnly: true }, generated: true },
+            { name: 'is_deletable', type: { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: false, isReadOnly: true }, generated: true },
+            { name: 'effective_targets', type: { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: false, isReadOnly: true }, generated: true },
+        ],
+        keys: [],
+        rowConstraints: []
+    },
+    relationalAdvertisement: {
+        isSet: true,
+        // Composite (schema, name): a view is unique per (schema, name) — guards
+        // against same-named views across schemas (main / temp / …).
+        keys: [[{ index: 0 }, { index: 1 }]],
+    },
+}, async function* (db, filterName) {
+    const nameFilter = (typeof filterName === 'string') ? filterName.toLowerCase() : null;
+    for (const schemaInstance of db.schemaManager._getAllSchemas()) {
+        for (const view of schemaInstance.getAllViews()) {
+            if (nameFilter !== null && view.name.toLowerCase() !== nameFilter)
+                continue;
+            let info;
+            try {
+                info = deriveViewInfo(db, view);
+            }
+            catch (error) {
+                // Per-view conservative fallback: a body that fails to plan (stale
+                // source, unsupported shape) yields the all-`NO` / `[]` row rather
+                // than throwing the whole TVF. Logged so a genuinely unexpected
+                // failure is not silently swallowed.
+                log('conservative row for view %s.%s: %s', schemaInstance.name, view.name, error instanceof Error ? error.message : String(error));
+                info = CONSERVATIVE_VIEW_INFO;
+            }
+            yield [
+                schemaInstance.name,
+                view.name,
+                yesNo(info.isInsertableInto),
+                yesNo(info.isUpdatable),
+                yesNo(info.isDeletable),
+                jsonStringify(info.effectiveTargets),
+            ];
+        }
+    }
+});
+/**
+ * Derive the per-column updateability rows for a base table, plain view, or
+ * maintained table (materialized view).
+ *
+ * **Base table** (`_findTable` hit) — every non-generated column is trivially a
+ * `base` write target; generated columns are computed/read-only. The `schema`
+ * comes straight off the resolved `TableSchema.schemaName`.
+ *
+ * **Plain view** (first `getView` hit across schemas, main→temp→attached order
+ * mirroring `_findTable`) — plan the body **logically** (via `_buildPlan`, not
+ * `getPlan`, for the same lineage-preservation reason as `deriveViewInfo`) and
+ * read each output attribute's backward `updateLineage` site. A `base` site
+ * (unwrapped through `null-extended`) that resolves to a `TableReferenceNode`
+ * is updatable and carries its base table/column trace; everything else is
+ * read-only with `null` trace.
+ *
+ * Throws `'<name>' not found` when neither resolves (parity with `table_info`'s
+ * required-target posture — `column_info` takes a *required* name, unlike
+ * `view_info`'s optional filter). A view body that fails to plan or yields no
+ * relational output produces *no rows* (logged) — the conservative, never-throw
+ * posture `view_info` takes, but at row granularity there is no all-`NO` row to
+ * emit.
+ *
+ * **Maintained table** (a `TableSchema` carrying a `TableDerivation` — what
+ * `create materialized view` produces; detected via `isMaintainedTable`, never a
+ * name pattern) — write-through inherits the view-updateability rules
+ * (`maintainedTableViewLike` routes DML through the same view-mutation rewrite a
+ * plain view uses), so the per-column rows come from the SAME derivation-body
+ * lineage walk a plain view gets, not the trivially-all-updatable base branch:
+ * passthrough/rename columns report their source base column and
+ * `is_updatable = 'YES'`; non-invertible expression columns report `'NO'` with
+ * null trace. The table's own registered columns are the authoritative output
+ * names (the derivation's rename list is already folded into them), so they
+ * override the body attribute names positionally. A derivation body that fails
+ * to plan (e.g. stale source) degrades to conservative read-only rows over the
+ * registered columns — unlike the view path's no-rows fallback, the columns ARE
+ * known here. `view_info` continues to exclude maintained tables (its per-view
+ * surface stays plain-view-only); the two functions tell one consistent
+ * lineage story through this shared walk.
+ */
+function deriveColumnInfo(db, name) {
+    // Base table first (mirrors table_info's `_findTable`-only resolution).
+    const table = db._findTable(name);
+    if (table) {
+        if (isMaintainedTable(table)) {
+            const columnNames = table.columns.map(c => c.name);
+            try {
+                return deriveBodyColumnRows(db, table.schemaName, table.name, table.derivation.selectAst, columnNames);
+            }
+            catch (error) {
+                // Conservative fallback: the registered columns are known even when the
+                // derivation body fails to plan — report each read-only with null trace.
+                log('column_info: conservative rows for maintained table %s.%s: %s', table.schemaName, table.name, error instanceof Error ? error.message : String(error));
+                return columnNames.map((columnName, i) => ({
+                    schema: table.schemaName,
+                    objectName: table.name,
+                    cid: i,
+                    columnName,
+                    isUpdatable: false,
+                    baseTable: null,
+                    baseColumn: null,
+                }));
+            }
+        }
+        return table.columns.map((col, i) => {
+            const updatable = !col.generated;
+            return {
+                schema: table.schemaName,
+                objectName: table.name,
+                cid: i,
+                columnName: col.name,
+                isUpdatable: updatable,
+                baseTable: updatable ? table.name : null,
+                baseColumn: updatable ? col.name : null,
+            };
+        });
+    }
+    // View fallback: first `getView` hit across schemas (main → temp → attached,
+    // the insertion order `_getAllSchemas` yields — same order `_findTable` uses).
+    let view;
+    let schemaName;
+    for (const schemaInstance of db.schemaManager._getAllSchemas()) {
+        const v = schemaInstance.getView(name);
+        if (v) {
+            view = v;
+            schemaName = schemaInstance.name;
+            break;
+        }
+    }
+    if (!view || schemaName === undefined) {
+        throw new QuereusError(`'${name}' not found`, StatusCode.ERROR);
+    }
+    try {
+        return deriveBodyColumnRows(db, schemaName, view.name, view.selectAst);
+    }
+    catch (error) {
+        // A body that fails to plan (stale source, unsupported shape) yields no
+        // rows rather than throwing the whole TVF — logged so a genuinely
+        // unexpected failure is not silently swallowed.
+        log('column_info: no rows for view %s.%s: %s', schemaName, view.name, error instanceof Error ? error.message : String(error));
+        return [];
+    }
+}
+/**
+ * The shared body-lineage walk behind `column_info`'s view AND maintained-table
+ * branches: plan `selectAst` **logically** (via `_buildPlan`, not `getPlan`, for
+ * the same lineage-preservation reason as `deriveViewInfo`) and read each output
+ * attribute's backward `updateLineage` site — the same classification the
+ * write-through rewrite applies, so the static surface agrees with the dynamic
+ * `propagate()` truth for both surfaces. Throws on plan failure; each caller
+ * supplies its own conservative fallback. `columnNames`, when given (the
+ * maintained-table caller), positionally overrides the body attribute names —
+ * the owning table's registered columns are the authoritative output names.
+ * Lineage classification (set-op flag membership) still keys off the body
+ * attribute names the AST probes report.
+ */
+function deriveBodyColumnRows(db, schemaName, objectName, selectAst, columnNames) {
+    const { plan } = db._buildPlan([selectAst]);
+    const root = plan.getRelations()[0];
+    if (!root)
+        return [];
+    const nodes = collectBodyNodes(root);
+    // Set-operation membership body: every column is writable through an *effect*, not a
+    // base mapping — a membership flag flips its branch's presence (insert/delete), a data
+    // column fans out to its member branches (`set-op-membership-write`). So each reports
+    // `is_updatable = 'YES'` with `base_table` / `base_column` = null (no single base
+    // column), the same writable-through-effect shape a join-side existence flag reports.
+    //
+    // Gated on the branch-writability shape probe (parity with `deriveViewInfo`): a body
+    // the dynamic write rejects (outer LIMIT/OFFSET, non-SELECT right, `select *` leg,
+    // computed leg, mismatched leg arity) falls THROUGH to the per-column walk below
+    // instead of the all-`YES` short-circuit. That walk reports every column non-updatable
+    // with null base — a `SetOperationNode` root threads `updateLineage` ONLY for its
+    // membership flags (a read-only `set-op-branch` existence site) and NONE for its data
+    // columns, so `baseSiteOf` resolves no base for either, matching the dynamic reject.
+    // Nested (subtree) operands (`nestable-flagged-set-ops`): data columns + own flags stay
+    // writable-through-effect (`YES`); a SURFACED INNER flag (`inB`/`inC`) is read-only (`NO`) —
+    // writing it addresses a branch inside a subtree (product-coordinate `set-op-membership-nested`).
+    // Empty surfaced-inner set (the binary case) => all-`YES`, unchanged.
+    if (isSetOpMembershipBody(selectAst) && isSetOpBranchWritable(selectAst)) {
+        const innerFlags = new Set(surfacedInnerFlagNames(selectAst).map(n => n.toLowerCase()));
+        return root.getAttributes().map((attr, i) => ({
+            schema: schemaName,
+            objectName,
+            cid: i,
+            columnName: columnNames?.[i] ?? attr.name,
+            isUpdatable: !innerFlags.has(attr.name.toLowerCase()),
+            baseTable: null,
+            baseColumn: null,
+        }));
+    }
+    // Flag-less predicate-honest set-op body (`set-op-flagless-predicate-honest-writes`):
+    // a plain (writable) data column reports `is_updatable = YES` (its data-column fan-out
+    // writes the base column through every consistent leg); a literal **discriminator**
+    // column reports `NO` (read-only — it routes rows and has no base inverse, surfacing
+    // `no-inverse` on the dynamic write). Both with null base (no single base column). Gated
+    // on the same shape recognizer as `deriveViewInfo`, so the static and dynamic answers
+    // cannot drift.
+    if (isSetOpFlaglessWritableBody(selectAst)) {
+        const discriminators = new Set(flaglessDiscriminatorColumnNames(selectAst).map(n => n.toLowerCase()));
+        return root.getAttributes().map((attr, i) => ({
+            schema: schemaName,
+            objectName,
+            cid: i,
+            columnName: columnNames?.[i] ?? attr.name,
+            isUpdatable: !discriminators.has(attr.name.toLowerCase()),
+            baseTable: null,
+            baseColumn: null,
+        }));
+    }
+    // Non-decomposable join shape gate: cross / comma / subquery-source join bodies
+    // are not write-through-able. `propagate()` decomposes an n-way (≥2) equi-join —
+    // `inner`/`left`/`right`/`full` (RIGHT now admitted, the LEFT mirror; FULL self-conservatizes), composite-PK
+    // sides and self-joins included
+    // (`isDecomposableJoinBody`, the boolean shadow of `collectJoinSources`) — and
+    // rejects every other join shape, so without this gate `baseSiteOf` would resolve
+    // their bases and over-report `is_updatable = 'YES'`. Outer joins ARE decomposable
+    // now; their non-preserved columns are reported updatable per-column below when a
+    // preserved anchor exists (matching the dynamic matched-update / null-extended-insert
+    // materialization), rather than short-circuiting the whole view to all-`NO`.
+    const unsupportedJoinShape = isJoinBody(selectAst) && !isDecomposableJoinBody(selectAst);
+    const tableRefsById = buildTableRefsById(nodes);
+    const rootLineage = root.physical?.updateLineage;
+    const attrs = root.getAttributes();
+    // Whether the body exposes a PRESERVED base column — a preserved anchor that pins
+    // each view row's identity. A LEFT join has one (the preserved side); a FULL outer
+    // join (every column null-extended) does not, so a non-preserved update there stays
+    // deferred. A non-preserved (`null-extended`) column is now updatable WHEN such an
+    // anchor exists: the matched-update / null-extended-insert materialization keys off
+    // it (`view-write-optional-member-transitions`), matching the dynamic accept.
+    const hasPreservedBase = !unsupportedJoinShape && attrs.some(a => {
+        const s = baseSiteOf(rootLineage?.get(a.id));
+        return s !== undefined && !s.nullExtended;
+    });
+    const rows = [];
+    for (let i = 0; i < attrs.length; i++) {
+        const attr = attrs[i];
+        const site = unsupportedJoinShape ? undefined : rootLineage?.get(attr.id);
+        const bs = baseSiteOf(site);
+        const ref = bs ? tableRefsById.get(bs.table) : undefined;
+        // A join-side `exists … as` existence flag has NO base column but is writable
+        // through an *effect* — its flip inserts/deletes the non-preserved side — when a
+        // preserved anchor pins each row's identity (`outer-join-existence-column`).
+        // Report it `is_updatable = 'YES'` with `base_table` / `base_column` = null (it
+        // maps to no base column), matching the dynamic `propagate()` accept. Gated on a
+        // preserved anchor like the non-preserved column: a FULL outer (none) stays
+        // deferred. A `set-op-branch` existence flag is READ-ONLY in this read half
+        // (`set-op-membership-read`) — it reports `is_updatable = 'NO'` with null base
+        // (a set-op view has no preserved base anchor anyway); the write half flips it on.
+        const isExistence = site?.kind === 'existence' && site.component.kind === 'join-side' && hasPreservedBase;
+        // An authored (`with inverse`) column is writable (and insertable) through its
+        // put expressions — report it updatable, with the base trace populated only
+        // for a single-put inverse (a multi-target inverse maps to no single base
+        // column, the same null-base shape an existence flag reports). Agrees with
+        // the dynamic spines, which route authored sites on UPDATE and INSERT alike.
+        const authored = site?.kind === 'authored' ? site : undefined;
+        const authoredPutRef = authored && authored.puts.length === 1
+            ? tableRefsById.get(authored.puts[0].table)
+            : undefined;
+        // Updatable iff a base site resolves to a producing TableReferenceNode. A
+        // PRESERVED base column is always updatable; a non-preserved (`null-extended`)
+        // column is updatable when the body has a preserved anchor (the matched-update /
+        // null-extended-insert materialization pins identity off it), and read-only only
+        // when no anchor exists (a FULL outer — write-through stays deferred there). A
+        // base id without a resolved ref should not happen; fail conservative if it does.
+        const updatable = isExistence || authored !== undefined || !!(bs && ref && (!bs.nullExtended || hasPreservedBase));
+        // Base trace is reported only for an actual base column write (an existence flag
+        // is updatable but has no base mapping).
+        const hasBaseTrace = updatable && bs !== undefined && ref !== undefined;
+        rows.push({
+            schema: schemaName,
+            objectName,
+            cid: i,
+            columnName: columnNames?.[i] ?? attr.name,
+            isUpdatable: updatable,
+            baseTable: hasBaseTrace ? ref.tableSchema.name : authoredPutRef ? authoredPutRef.tableSchema.name : null,
+            baseColumn: hasBaseTrace ? bs.baseColumn : authoredPutRef ? authored.puts[0].baseColumn : null,
+        });
+    }
+    return rows;
+}
+// Per-column updateability function (table-valued function)
+export const columnInfoFunc = createIntegratedTableValuedFunction({
+    name: 'column_info',
+    numArgs: 1,
+    deterministic: false, // Schema (and therefore lineage) can change
+    returnType: {
+        typeClass: 'relation',
+        isReadOnly: true,
+        isSet: false,
+        columns: [
+            { name: 'schema', type: { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: false, isReadOnly: true }, generated: true },
+            { name: 'name', type: { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: false, isReadOnly: true }, generated: true },
+            { name: 'cid', type: { typeClass: 'scalar', logicalType: INTEGER_TYPE, nullable: false, isReadOnly: true }, generated: true },
+            { name: 'column_name', type: { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: false, isReadOnly: true }, generated: true },
+            { name: 'is_updatable', type: { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: false, isReadOnly: true }, generated: true },
+            { name: 'base_table', type: { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: true, isReadOnly: true }, generated: true },
+            { name: 'base_column', type: { typeClass: 'scalar', logicalType: TEXT_TYPE, nullable: true, isReadOnly: true }, generated: true },
+        ],
+        keys: [],
+        rowConstraints: []
+    },
+    relationalAdvertisement: {
+        isSet: true,
+        // `cid` (column 2) is the column ordinal — unique per emitted row.
+        keys: [[{ index: 2 }]],
+    },
+}, async function* (db, tableName) {
+    if (typeof tableName !== 'string') {
+        throw new QuereusError('column_info() requires a table or view name string argument', StatusCode.ERROR);
+    }
+    for (const r of deriveColumnInfo(db, tableName)) {
+        yield [
+            r.schema,
+            r.objectName,
+            r.cid,
+            r.columnName,
+            yesNo(r.isUpdatable),
+            r.baseTable,
+            r.baseColumn,
+        ];
+    }
+});
 //# sourceMappingURL=schema.js.map