datanotes 3.4.1 → 3.4.2

package/dist/api/extension-columns.d.cts

@@ -0,0 +1,64 @@
+/**
+ * Column bindings of an extension: the manifest columns of a dependency role may be bound to
+ * columns of another name in the user's table (`--map role.column=column`). The manifest names
+ * columns in its view queries, CHECKs and link filters; this module rewrites those names to the
+ * bound ones, following link columns from role to role (`book.author.name`). Pure: no I/O.
+ *
+ * What it cannot rewrite safely it reports as an issue (fail closed), never guesses: a mapped
+ * column named in the outer clauses of a union view, or under a query key it does not know.
+ */
+import type { ExtensionManifest, ManifestColumn } from "./extension-manifest.cjs";
+/** role → (manifest column → bound column); only the columns whose names differ matter. */
+export type ColumnMap = Readonly<Record<string, Readonly<Record<string, string>>>>;
+/** A place where a mapped column is named and cannot be rewritten. */
+export interface ColumnIssue {
+    role: string;
+    column: string;
+    /** Where it is named: `view vw_x (union order_by)`. */
+    where: string;
+}
+type Obj = Record<string, unknown>;
+/** Rewrites the column names of bound roles; `issues` collects what it could not rewrite. */
+export declare class ColumnBinder {
+    private readonly manifest;
+    readonly issues: ColumnIssue[];
+    private readonly map;
+    constructor(manifest: Pick<ExtensionManifest, "tables">, map: ColumnMap);
+    /** True when no role has a column bound to another name: every rewrite is the identity. */
+    get empty(): boolean;
+    /** The bound name of a role's manifest column. */
+    name(role: string | null, column: string): string;
+    /** The manifest columns of a role bound to another name. */
+    mapped(role: string): string[];
+    /** The role a link column of `role` points to (`ref: "@x"`, or `self`), or null. */
+    private linkRole;
+    /** A dotted column path read on `role`: each part on the role the previous link points to. */
+    path(role: string | null, dotted: string): string;
+    /** A group_by or join expression: `col`, `path`, `date(col)`, `date(col)+1`. */
+    expr(role: string | null, e: string): string;
+    /** A `where` filter (or a CHECK) on `role`: keys are column paths; `or` / `and` / `not` nest. */
+    where(role: string | null, where: unknown): unknown;
+    /** A column spec of `role`: its link filter (`ref_where`), `ref_by`, `inverse`. */
+    column(role: string, c: ManifestColumn): ManifestColumn;
+    /** A view query: the tables it reads are roles (`@meal`); every column it names follows them. */
+    query(view: string, q: Obj): Obj;
+    private order;
+    /** `count`, `count:col`, `sum:meal.kcal`. */
+    private aggregate;
+    /** `{table, on: {left expr: right expr}, as, type, columns, where}`: `columns` and `where` read the joined table. */
+    private join;
+    /** `{union: [{table, columns, where}], …}`: each part on its role; the outer clauses read every part, so a mapped column there is an issue. */
+    private union;
+    /** A clause the binder does not rewrite: an issue for each mapped column it names. */
+    private unknown;
+    /**
+     * The mapped columns a value names, where nothing rewrites it: a word that is a mapped column of
+     * one of `roles`, or a later part of a dotted path (`author.name`) that is a mapped column of any
+     * role. `keys(key, inKeys)` tells whether the keys under `key` are names too.
+     */
+    named(v: unknown, roles: string[], keys: (key: string, inKeys: boolean) => boolean): {
+        role: string;
+        column: string;
+    }[];
+}
+export {};

package/dist/api/extension-columns.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Column bindings of an extension: the manifest columns of a dependency role may be bound to
+ * columns of another name in the user's table (`--map role.column=column`). The manifest names
+ * columns in its view queries, CHECKs and link filters; this module rewrites those names to the
+ * bound ones, following link columns from role to role (`book.author.name`). Pure: no I/O.
+ *
+ * What it cannot rewrite safely it reports as an issue (fail closed), never guesses: a mapped
+ * column named in the outer clauses of a union view, or under a query key it does not know.
+ */
+import type { ExtensionManifest, ManifestColumn } from "./extension-manifest.js";
+/** role → (manifest column → bound column); only the columns whose names differ matter. */
+export type ColumnMap = Readonly<Record<string, Readonly<Record<string, string>>>>;
+/** A place where a mapped column is named and cannot be rewritten. */
+export interface ColumnIssue {
+    role: string;
+    column: string;
+    /** Where it is named: `view vw_x (union order_by)`. */
+    where: string;
+}
+type Obj = Record<string, unknown>;
+/** Rewrites the column names of bound roles; `issues` collects what it could not rewrite. */
+export declare class ColumnBinder {
+    private readonly manifest;
+    readonly issues: ColumnIssue[];
+    private readonly map;
+    constructor(manifest: Pick<ExtensionManifest, "tables">, map: ColumnMap);
+    /** True when no role has a column bound to another name: every rewrite is the identity. */
+    get empty(): boolean;
+    /** The bound name of a role's manifest column. */
+    name(role: string | null, column: string): string;
+    /** The manifest columns of a role bound to another name. */
+    mapped(role: string): string[];
+    /** The role a link column of `role` points to (`ref: "@x"`, or `self`), or null. */
+    private linkRole;
+    /** A dotted column path read on `role`: each part on the role the previous link points to. */
+    path(role: string | null, dotted: string): string;
+    /** A group_by or join expression: `col`, `path`, `date(col)`, `date(col)+1`. */
+    expr(role: string | null, e: string): string;
+    /** A `where` filter (or a CHECK) on `role`: keys are column paths; `or` / `and` / `not` nest. */
+    where(role: string | null, where: unknown): unknown;
+    /** A column spec of `role`: its link filter (`ref_where`), `ref_by`, `inverse`. */
+    column(role: string, c: ManifestColumn): ManifestColumn;
+    /** A view query: the tables it reads are roles (`@meal`); every column it names follows them. */
+    query(view: string, q: Obj): Obj;
+    private order;
+    /** `count`, `count:col`, `sum:meal.kcal`. */
+    private aggregate;
+    /** `{table, on: {left expr: right expr}, as, type, columns, where}`: `columns` and `where` read the joined table. */
+    private join;
+    /** `{union: [{table, columns, where}], …}`: each part on its role; the outer clauses read every part, so a mapped column there is an issue. */
+    private union;
+    /** A clause the binder does not rewrite: an issue for each mapped column it names. */
+    private unknown;
+    /**
+     * The mapped columns a value names, where nothing rewrites it: a word that is a mapped column of
+     * one of `roles`, or a later part of a dotted path (`author.name`) that is a mapped column of any
+     * role. `keys(key, inKeys)` tells whether the keys under `key` are names too.
+     */
+    named(v: unknown, roles: string[], keys: (key: string, inKeys: boolean) => boolean): {
+        role: string;
+        column: string;
+    }[];
+}
+export {};

package/dist/api/extension-plan.d.cts

@@ -48,7 +48,7 @@ export interface TableChoice {
     proposed: boolean;
     candidates: string[];
 }
-export type ProblemCode = "engine_too_old" | "unknown_role" | "table_not_found" | "table_missing" | "table_exists" | "owned_create" | "ambiguous_dependency" | "missing_column" | "column_differs" | "owned_column_map" | "migration_conflict" | "base_differs" | "view_exists" | "tool_name_taken" | "token_exists" | "too_many_operations" | "already_installed" | "downgrade" | "same_version";
+export type ProblemCode = "engine_too_old" | "unknown_role" | "table_not_found" | "table_missing" | "table_exists" | "owned_create" | "ambiguous_dependency" | "missing_column" | "column_differs" | "owned_column_map" | "column_map_unsupported" | "migration_conflict" | "base_differs" | "view_exists" | "tool_name_taken" | "token_exists" | "too_many_operations" | "already_installed" | "downgrade" | "same_version";
 /** Something that keeps the plan from being written: what is wrong, how to fix it, where to read more. */
 export interface PlanProblem {
     code: ProblemCode;

package/dist/api/extension-plan.d.ts

@@ -48,7 +48,7 @@ export interface TableChoice {
     proposed: boolean;
     candidates: string[];
 }
-export type ProblemCode = "engine_too_old" | "unknown_role" | "table_not_found" | "table_missing" | "table_exists" | "owned_create" | "ambiguous_dependency" | "missing_column" | "column_differs" | "owned_column_map" | "migration_conflict" | "base_differs" | "view_exists" | "tool_name_taken" | "token_exists" | "too_many_operations" | "already_installed" | "downgrade" | "same_version";
+export type ProblemCode = "engine_too_old" | "unknown_role" | "table_not_found" | "table_missing" | "table_exists" | "owned_create" | "ambiguous_dependency" | "missing_column" | "column_differs" | "owned_column_map" | "column_map_unsupported" | "migration_conflict" | "base_differs" | "view_exists" | "tool_name_taken" | "token_exists" | "too_many_operations" | "already_installed" | "downgrade" | "same_version";
 /** Something that keeps the plan from being written: what is wrong, how to fix it, where to read more. */
 export interface PlanProblem {
     code: ProblemCode;

package/dist/datanotes.cjs

@@ -38937,11 +38937,223 @@ var init_extension_host = __esm({
   }
 });
 
+// src/api/extension-columns.ts
+function roleOf(v) {
+  if (typeof v !== "string") return null;
+  const m = ROLE_REF.exec(v);
+  return m ? m[1] : null;
+}
+var isObject5, LOGICAL2, DATE_EXPR3, QUERY_KEYS, JOIN_KEYS, UNION_PART_KEYS, ColumnBinder;
+var init_extension_columns = __esm({
+  "src/api/extension-columns.ts"() {
+    "use strict";
+    init_extension_manifest();
+    isObject5 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+    LOGICAL2 = /* @__PURE__ */ new Set(["or", "and", "not"]);
+    DATE_EXPR3 = /^date\((.+)\)([+-]\d+)?$/;
+    QUERY_KEYS = /* @__PURE__ */ new Set(["table", "columns", "where", "order_by", "limit", "offset", "expand", "join", "group_by", "aggregates", "include_body", "union"]);
+    JOIN_KEYS = /* @__PURE__ */ new Set(["table", "on", "as", "type", "columns", "where"]);
+    UNION_PART_KEYS = /* @__PURE__ */ new Set(["table", "columns", "where"]);
+    ColumnBinder = class {
+      constructor(manifest, map) {
+        this.manifest = manifest;
+        this.issues = [];
+        this.map = {};
+        for (const [role, cols] of Object.entries(map)) {
+          const differing = Object.entries(cols).filter(([from, to]) => from !== to);
+          if (differing.length > 0) this.map[role] = Object.fromEntries(differing);
+        }
+      }
+      /** True when no role has a column bound to another name: every rewrite is the identity. */
+      get empty() {
+        return Object.keys(this.map).length === 0;
+      }
+      /** The bound name of a role's manifest column. */
+      name(role, column) {
+        return role === null ? column : this.map[role]?.[column] ?? column;
+      }
+      /** The manifest columns of a role bound to another name. */
+      mapped(role) {
+        return Object.keys(this.map[role] ?? {});
+      }
+      /** The role a link column of `role` points to (`ref: "@x"`, or `self`), or null. */
+      linkRole(role, column) {
+        const c = typeof column === "string" ? this.manifest.tables[role]?.columns.find((x) => x.name === column) : column;
+        if (!c || c.ref === void 0) return null;
+        if (!(c.type === "link" || c.type === "list" && c.items === "link")) return null;
+        return c.ref === "self" ? role : roleOf(c.ref);
+      }
+      /** A dotted column path read on `role`: each part on the role the previous link points to. */
+      path(role, dotted) {
+        if (role === null || this.empty) return dotted;
+        const parts = dotted.split(".");
+        const out2 = [];
+        let cur = role;
+        for (const part of parts) {
+          out2.push(this.name(cur, part));
+          cur = cur === null ? null : this.linkRole(cur, part);
+        }
+        return out2.join(".");
+      }
+      /** A group_by or join expression: `col`, `path`, `date(col)`, `date(col)+1`. */
+      expr(role, e) {
+        const d = DATE_EXPR3.exec(e);
+        return d ? `date(${this.path(role, d[1])})${d[2] ?? ""}` : this.path(role, e);
+      }
+      /** A `where` filter (or a CHECK) on `role`: keys are column paths; `or` / `and` / `not` nest. */
+      where(role, where) {
+        if (!isObject5(where) || role === null || this.empty) return where;
+        const out2 = {};
+        for (const [k, v] of Object.entries(where)) {
+          if (LOGICAL2.has(k)) out2[k] = Array.isArray(v) ? v.map((w) => this.where(role, w)) : this.where(role, v);
+          else out2[this.path(role, k)] = v;
+        }
+        return out2;
+      }
+      /** A column spec of `role`: its link filter (`ref_where`), `ref_by`, `inverse`. */
+      column(role, c) {
+        if (this.empty) return c;
+        let out2 = c;
+        const target = this.linkRole(role, c);
+        if (c.ref_where !== void 0) out2 = { ...out2, ref_where: this.where(target, c.ref_where) };
+        if (isObject5(c.ref_by)) {
+          const by = c.ref_by;
+          const col = this.name(role, String(by.column));
+          const tgt = this.name(target, String(by.target_column ?? by.column));
+          const { target_column: _t, ...rest } = by;
+          out2 = { ...out2, ref_by: { ...rest, column: col, ...tgt !== col ? { target_column: tgt } : {} } };
+        }
+        if (typeof c.inverse === "string") out2 = { ...out2, inverse: this.name(target, c.inverse) };
+        return out2;
+      }
+      /** A view query: the tables it reads are roles (`@meal`); every column it names follows them. */
+      query(view, q) {
+        if (this.empty) return q;
+        if (Array.isArray(q.union)) return this.union(view, q);
+        const role = roleOf(q.table);
+        const out2 = {};
+        const aliases = new Set(isObject5(q.aggregates) ? Object.keys(q.aggregates) : []);
+        const col = (v) => aliases.has(v) ? v : this.path(role, v);
+        for (const [k, v] of Object.entries(q)) {
+          switch (k) {
+            case "columns":
+            case "expand":
+              out2[k] = Array.isArray(v) ? v.map((x) => typeof x === "string" ? col(x) : x) : v;
+              break;
+            case "order_by":
+              out2[k] = Array.isArray(v) ? v.map((x) => this.order(x, col)) : this.order(v, col);
+              break;
+            case "where":
+              out2[k] = this.where(role, v);
+              break;
+            case "group_by":
+              out2[k] = Array.isArray(v) ? v.map((x) => typeof x === "string" ? this.expr(role, x) : x) : typeof v === "string" ? this.expr(role, v) : v;
+              break;
+            case "aggregates":
+              out2[k] = isObject5(v) ? Object.fromEntries(Object.entries(v).map(([a, spec2]) => [a, this.aggregate(role, spec2)])) : v;
+              break;
+            case "join":
+              out2[k] = isObject5(v) ? this.join(view, role, v) : v;
+              break;
+            default:
+              if (!QUERY_KEYS.has(k)) this.unknown(view, [role], k, v);
+              out2[k] = v;
+          }
+        }
+        return out2;
+      }
+      order(v, col) {
+        if (typeof v !== "string") return v;
+        return v.startsWith("-") ? `-${col(v.slice(1))}` : col(v);
+      }
+      /** `count`, `count:col`, `sum:meal.kcal`. */
+      aggregate(role, spec2) {
+        if (typeof spec2 !== "string") return spec2;
+        const i = spec2.indexOf(":");
+        return i < 0 ? spec2 : `${spec2.slice(0, i)}:${this.path(role, spec2.slice(i + 1))}`;
+      }
+      /** `{table, on: {left expr: right expr}, as, type, columns, where}`: `columns` and `where` read the joined table. */
+      join(view, left, j) {
+        const right = roleOf(j.table);
+        const out2 = {};
+        for (const [k, v] of Object.entries(j)) {
+          if (k === "on" && isObject5(v)) {
+            out2[k] = Object.fromEntries(Object.entries(v).map(([a, b]) => [this.expr(left, a), typeof b === "string" ? this.expr(right, b) : b]));
+          } else if (k === "columns" && Array.isArray(v)) out2[k] = v.map((x) => typeof x === "string" ? this.path(right, x) : x);
+          else if (k === "where") out2[k] = this.where(right, v);
+          else {
+            if (!JOIN_KEYS.has(k)) this.unknown(view, [left, right], `join.${k}`, v);
+            out2[k] = v;
+          }
+        }
+        return out2;
+      }
+      /** `{union: [{table, columns, where}], …}`: each part on its role; the outer clauses read every part, so a mapped column there is an issue. */
+      union(view, q) {
+        const roles = [];
+        const parts = q.union.map((p) => {
+          if (!isObject5(p)) return p;
+          const role = roleOf(p.table);
+          roles.push(role);
+          const out2 = {};
+          for (const [k, v] of Object.entries(p)) {
+            if (k === "columns" && Array.isArray(v)) out2[k] = v.map((x) => typeof x === "string" ? this.path(role, x) : x);
+            else if (k === "where") out2[k] = this.where(role, v);
+            else {
+              if (!UNION_PART_KEYS.has(k)) this.unknown(view, [role], `union.${k}`, v);
+              out2[k] = v;
+            }
+          }
+          return out2;
+        });
+        for (const [k, v] of Object.entries(q)) if (k !== "union") this.unknown(view, roles, `union ${k}`, v);
+        return { ...q, union: parts };
+      }
+      /** A clause the binder does not rewrite: an issue for each mapped column it names. */
+      unknown(view, roles, key2, v) {
+        for (const n of this.named(v, roles.filter((r) => r !== null), () => true)) this.issues.push({ ...n, where: `view ${view} (${key2})` });
+      }
+      /**
+       * The mapped columns a value names, where nothing rewrites it: a word that is a mapped column of
+       * one of `roles`, or a later part of a dotted path (`author.name`) that is a mapped column of any
+       * role. `keys(key, inKeys)` tells whether the keys under `key` are names too.
+       */
+      named(v, roles, keys) {
+        const words = /* @__PURE__ */ new Set();
+        const tails = /* @__PURE__ */ new Set();
+        const text5 = (x) => {
+          for (const w of x.split(/[^A-Za-z0-9_.]+/)) {
+            const parts = w.split(".");
+            if (parts.length === 1) words.add(w);
+            else for (const p of parts.slice(1)) tails.add(p);
+          }
+        };
+        const walk = (x, inKeys) => {
+          if (typeof x === "string") text5(x);
+          else if (Array.isArray(x)) x.forEach((y) => walk(y, inKeys));
+          else if (isObject5(x)) {
+            for (const [k, y] of Object.entries(x)) {
+              if (inKeys) text5(k);
+              walk(y, keys(k, inKeys));
+            }
+          }
+        };
+        walk(v, keys("", false));
+        const out2 = [];
+        for (const role of Object.keys(this.map)) {
+          for (const column of this.mapped(role)) if (tails.has(column) || roles.includes(role) && words.has(column)) out2.push({ role, column });
+        }
+        return out2;
+      }
+    };
+  }
+});
+
 // src/api/extension-plan.ts
 function stable(v) {
   const walk = (x) => {
     if (Array.isArray(x)) return x.map(walk);
-    if (isObject5(x)) {
+    if (isObject6(x)) {
       const out2 = {};
       for (const k of Object.keys(x).sort()) out2[k] = walk(x[k]);
       return out2;
@@ -39115,6 +39327,10 @@ function planChanges(input) {
   for (const role of m.roles) tables[role] = choiceOf.get(role)?.table ?? `@${role}`;
   const bind = (v) => bindRoles(v, tables);
   const existing = (c) => c.decision === "adopt" || c.decision === "match";
+  const columnMap = {};
+  for (const c of input.chosen) if (!c.owned && c.decision === "match") columnMap[c.role] = { ...recorded[c.role]?.columns ?? {}, ...choices.columns[c.role] ?? {} };
+  const binder = new ColumnBinder(m, columnMap);
+  const bindColumn = (role, c) => bind(spec(binder.column(role, c)));
   const model = /* @__PURE__ */ new Map();
   for (const c of input.chosen) if (existing(c)) model.set(c.table, modelTable(input.described[c.table] ?? { qualified: c.table, columns: [] }));
   const views = new Set(input.listing.views.map((v) => v.qualified));
@@ -39142,6 +39358,19 @@ function planChanges(input) {
           );
           continue;
         }
+        const touched = mappedNamed(raw);
+        if (touched !== null) {
+          migrationProblems.push(
+            problem(
+              "migration_conflict",
+              `migration ${g.version}: ${raw.op} names column ${touched.column} of ${touched.role}, which reads your column ${binder.name(touched.role, touched.column)}`,
+              `Rename your column to ${touched.column} with rename_column and run the command again without --map ${touched.role}.${touched.column}, or ask the extension's author.`,
+              EXT_DOCS.update,
+              { role: touched.role, column: touched.column }
+            )
+          );
+          continue;
+        }
         const op2 = bind(raw);
         const r = simulate(op2, g.version);
         if (typeof r === "string") {
@@ -39153,6 +39382,9 @@ function planChanges(input) {
       }
     }
   }
+  function mappedNamed(raw) {
+    return binder.named(raw, rolesNamed(raw), (k, inKeys) => inKeys || FILTER_KEYS.has(k))[0] ?? null;
+  }
   function qualify(op2) {
     return `${String(op2.catalog ?? catalog)}.${String(op2.schema ?? viewSchema)}.${String(op2.name)}`;
   }
@@ -39285,7 +39517,7 @@ function planChanges(input) {
         schema,
         name: tname,
         description: def.description,
-        columns: bind(def.columns.map(spec)),
+        columns: def.columns.map((c) => bindColumn(role, c)),
         ...def.filename !== void 0 ? { filename: def.filename } : {},
         ...def.aliases !== void 0 ? { aliases: def.aliases } : {}
       });
@@ -39294,8 +39526,8 @@ function planChanges(input) {
     }
     const actualCols = model.get(q).columns;
     for (const c of def.columns) {
-      const bound = bind(spec(c));
-      const actualName = choices.columns[role]?.[c.name] ?? recorded[role]?.columns?.[c.name] ?? c.name;
+      const bound = bindColumn(role, c);
+      const actualName = binder.name(role, c.name);
       const actual = actualCols.get(actualName);
       if (actual) {
         const diff = columnDifference(bound, actual, q, false);
@@ -39336,7 +39568,7 @@ function planChanges(input) {
     const q = t.table;
     const tags = { extension: name, extension_role: role };
     const instructions = def.instructions === void 0 ? void 0 : bind(def.instructions);
-    const constraint = (c) => ({ op: "add_constraint", table: q, name: c.name, check: bind(c.check), hint: c.hint });
+    const constraint = (c) => ({ op: "add_constraint", table: q, name: c.name, check: bind(binder.where(role, c.check)), hint: c.hint });
     if (t.decision === "create") {
       const [cat, schema, tname] = q.split(".");
       operations.push({
@@ -39345,7 +39577,7 @@ function planChanges(input) {
         schema,
         name: tname,
         description: def.description,
-        columns: bind(def.columns.map(spec)),
+        columns: def.columns.map((c) => bindColumn(role, c)),
         ...def.filename !== void 0 ? { filename: def.filename } : {},
         ...def.aliases !== void 0 ? { aliases: def.aliases } : {},
         ...instructions !== void 0 ? { instructions } : {},
@@ -39358,7 +39590,7 @@ function planChanges(input) {
     }
     const mt = model.get(q);
     for (const c of def.columns) {
-      const bound = bind(spec(c));
+      const bound = bindColumn(role, c);
       const actual = mt.columns.get(c.name);
       if (!actual) {
         operations.push({ op: "add_column", table: q, column: bound });
@@ -39382,7 +39614,7 @@ function planChanges(input) {
       if (!actual) {
         operations.push(constraint(c));
         t.changes.push(`add CHECK ${c.name}`);
-      } else if (stable(actual.check) !== stable(bind(c.check)) || actual.hint !== c.hint) {
+      } else if (stable(actual.check) !== stable(bind(binder.where(role, c.check))) || actual.hint !== c.hint) {
         operations.push({ op: "drop_constraint", table: q, name: c.name }, constraint(c));
         t.changes.push(`replace CHECK ${c.name}`);
       }
@@ -39410,13 +39642,14 @@ function planChanges(input) {
   for (const v of Object.keys(m.views)) {
     const def = m.views[v];
     const q = `${catalog}.${viewSchema}.${v}`;
+    const query = binder.query(v, def.query);
     const create = {
       op: "create_view",
       catalog,
       schema: viewSchema,
       name: v,
       description: def.description,
-      query: bind(def.query),
+      query: bind(query),
       ...def.aliases !== void 0 ? { aliases: def.aliases } : {},
       ...def.labels !== void 0 ? { labels: def.labels } : {}
     };
@@ -39425,7 +39658,7 @@ function planChanges(input) {
       viewPlan.changes.push(`create view ${v}`);
     } else if (action === "install") {
       reconcileProblems.push(problem("view_exists", `${q} exists already`, "Drop or rename that view (drop_view), or install with --schema <another schema>.", EXT_DOCS.install, { table: q }));
-    } else if (stable(oldManifest.views[v]) !== stable(def)) {
+    } else if (stable(oldManifest.views[v]) !== stable(def) || stable(query) !== stable(def.query)) {
       operations.push({ ...create, replace: true });
       viewPlan.changes.push(`replace view ${v}`);
     }
@@ -39441,6 +39674,17 @@ function planChanges(input) {
       if (m.tables[role] === void 0) notes.push(`${role} (${rt.table}) is no longer used by the extension: it stays in the database`);
     }
   }
+  for (const i of binder.issues) {
+    reconcileProblems.push(
+      problem(
+        "column_map_unsupported",
+        `${i.role}: ${i.where} names column ${i.column}, which reads your column ${binder.name(i.role, i.column)}: the installer cannot rewrite it there`,
+        `Rename your column to ${i.column} with rename_column and leave --map ${i.role}.${i.column} out, or ask the extension's author.`,
+        EXT_DOCS.tables,
+        { role: i.role, column: i.column }
+      )
+    );
+  }
   const toolProblems = [];
   const others = input.others.filter((o) => o.name !== name);
   const boundNames = (roles) => roles.map((r) => tables[r]);
@@ -39561,16 +39805,18 @@ function renderPlan(plan) {
   lines.push("", plan.agent_message, plan.summary);
   return lines.join("\n");
 }
-var AGENT_MESSAGE, MAX_OPERATIONS, isObject5, obj3, list2, tableName, isLink;
+var AGENT_MESSAGE, FILTER_KEYS, MAX_OPERATIONS, isObject6, obj3, list2, tableName, isLink;
 var init_extension_plan = __esm({
   "src/api/extension-plan.ts"() {
     "use strict";
+    init_extension_columns();
     init_extension_manifest();
     init_guidance();
     AGENT_MESSAGE = `For the agent installing this extension: show this plan to the user before anything is written. Where a table says "proposed", the installer chose it: ask the user to confirm it, to pick another table (--map <role>=<catalog.schema.table>, --map <role>.<column>=<column>), or to create it (--create <role>). Add a missing column only after the user agrees (--add <role>.<column>). Solve each problem the same way. Then run the same command again with the user's choices and --yes, only once the user approved the tables it creates or changes, the tools and the token's permissions.`;
+    FILTER_KEYS = /* @__PURE__ */ new Set(["check", "where", "ref_where", "query", "on"]);
     MAX_OPERATIONS = 200;
-    isObject5 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
-    obj3 = (v) => isObject5(v) ? v : {};
+    isObject6 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+    obj3 = (v) => isObject6(v) ? v : {};
     list2 = (v) => Array.isArray(v) ? v : [];
     tableName = (t, role) => t.name ?? role;
     isLink = (c) => c.type === "link" || c.type === "list" && c.items === "link";
@@ -40697,7 +40943,7 @@ __export(util_exports, {
   hexToUint8Array: () => hexToUint8Array,
   hide: () => hide,
   installLazyProp: () => installLazyProp,
-  isObject: () => isObject6,
+  isObject: () => isObject7,
   isPlainObject: () => isPlainObject2,
   issue: () => issue,
   joinValues: () => joinValues,
@@ -40904,11 +41150,11 @@ function esc(str3) {
 function slugify(input) {
   return input.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/[\s_-]+/g, "-").replace(/^-+|-+$/g, "");
 }
-function isObject6(data) {
+function isObject7(data) {
   return typeof data === "object" && data !== null && !Array.isArray(data);
 }
 function isPlainObject2(o) {
-  if (isObject6(o) === false)
+  if (isObject7(o) === false)
     return false;
   const ctor = o.constructor;
   if (ctor === void 0)
@@ -40916,7 +41162,7 @@ function isPlainObject2(o) {
   if (typeof ctor !== "function")
     return true;
   const prot = ctor.prototype;
-  if (isObject6(prot) === false)
+  if (isObject7(prot) === false)
     return false;
   if (Object.prototype.hasOwnProperty.call(prot, "isPrototypeOf") === false) {
     return false;
@@ -43315,7 +43561,7 @@ var init_schemas = __esm({
         }
         return propValues;
       });
-      const isObject7 = isObject6;
+      const isObject8 = isObject7;
       const catchall = def.catchall;
       let value;
       const memo2 = globalConfig.memoizer;
@@ -43323,7 +43569,7 @@ var init_schemas = __esm({
       inst._zod.parse = (payload, ctx) => {
         value ?? (value = _normalized.value);
         const input = payload.value;
-        if (!isObject7(input)) {
+        if (!isObject8(input)) {
           payload.issues.push({
             expected: "object",
             code: "invalid_type",
@@ -43459,7 +43705,7 @@ var init_schemas = __esm({
         return doc.compile();
       };
       let fastpass;
-      const isObject7 = isObject6;
+      const isObject8 = isObject7;
       const jit = !globalConfig.jitless;
       const allowsEval2 = allowsEval;
       const fastEnabled = jit && allowsEval2.value;
@@ -43468,7 +43714,7 @@ var init_schemas = __esm({
       inst._zod.parse = (payload, ctx) => {
         value ?? (value = _normalized.value);
         const input = payload.value;
-        if (!isObject7(input)) {
+        if (!isObject8(input)) {
           payload.issues.push({
             expected: "object",
             code: "invalid_type",
@@ -43568,7 +43814,7 @@ var init_schemas = __esm({
       const disc = cached(() => discriminatorMap(def));
       inst._zod.parse = (payload, ctx) => {
         const input = payload.value;
-        if (!isObject6(input)) {
+        if (!isObject7(input)) {
           payload.issues.push({
             code: "invalid_type",
             expected: "object",
@@ -77387,7 +77633,7 @@ function setUp(o, vault, home, explicit, self) {
 // src/node/service.ts
 init_local();
 init_hints();
-var VERSION = true ? "3.4.1" : "dev";
+var VERSION = true ? "3.4.2" : "dev";
 function parsePort(raw, from = "--port") {
   const n = /^\s*\d+\s*$/.test(raw) ? Number(raw) : NaN;
   if (n === 0 || Number.isInteger(n) && n >= 1024 && n <= 65535) return n;
@@ -78452,7 +78698,7 @@ Docs: https://datanotes.dev`;
 
 // src/node/cli.ts
 init_message();
-var VERSION2 = true ? "3.4.1" : "dev";
+var VERSION2 = true ? "3.4.2" : "dev";
 var consoleError = console.error;
 async function main5(argv = process.argv.slice(2)) {
   const [command, ...rest] = argv;

package/dist/docs/administration/extensions.md

@@ -89,7 +89,7 @@ Five options carry your choices. They apply to `install` and, except the last tw
 | `--catalog` | Sets the catalog of created tables and views.           | `--catalog work`                                        |
 | `--schema`  | Sets the schema of created owned tables and views.      | `--schema reading`                                      |
 
-Each option takes a comma-separated list. `--map role=catalog.schema.table` binds a table. `--map role.column=column` maps a column. A column of the extension’s own table keeps the extension’s name: you cannot map it.
+Each option takes a comma-separated list. `--map role=catalog.schema.table` binds a table. `--map role.column=column` maps a column of a table the extension depends on. The views, CHECKs and link filters of the extension then read your column, through links too. A column of the extension’s own table keeps the extension’s name: you cannot map it.
 
 The plan ends with a message for the AI agent that runs the install:
 
@@ -101,6 +101,7 @@ An agent never guesses. It shows the plan, asks the user, and runs the command a
 * `ambiguous_dependency`: several tables could be the role. Pass `--map` or `--create`.
 * `missing_column`: the matched table lacks a column. Map another column, or add it with `--add`.
 * `column_differs`: a column exists with another type or rule. Map another column or table.
+* `column_map_unsupported`: the extension names a mapped column where the installer cannot rewrite it, such as the outer clauses of a `union` view. Rename your column to the extension’s name and leave the mapping out.
 * `table_exists`: a table the extension would create exists already. Use it with `--map`, or pick another catalog.
 * `tool_name_taken`: a tool name is already an operation or a tool of another extension.
 * `token_exists`: a token named `ext-<name>` exists already.

package/dist/docs/api.md

@@ -1,6 +1,6 @@
 # Datanotes HTTP API
 
-> OpenAPI 3.1.0 description of the Datanotes 3.4.1 HTTP API: https://datanotes.dev/openapi.json
+> OpenAPI 3.1.0 description of the Datanotes 3.4.2 HTTP API: https://datanotes.dev/openapi.json
 
 Database of Markdown notes: tables of notes, rows, queries, history, a change feed and the vault's notes.