@malloy-publisher/server 0.0.232 → 0.0.234

package/src/service/connection.spec.ts

@@ -1,17 +1,26 @@
 import { DuckDBConnection } from "@malloydata/db-duckdb";
-import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import {
+   afterAll,
+   afterEach,
+   beforeEach,
+   describe,
+   expect,
+   it,
+} from "bun:test";
 import fs from "fs/promises";
 import os from "os";
 import path from "path";
 import sinon from "sinon";
 import { components } from "../api";
 import {
+   attachDuckLakeReadWrite,
    buildProxiedSslQuery,
    createEnvironmentConnections,
    resolveProxiedTls,
    testConnectionConfig,
 } from "./connection";
 import { assembleEnvironmentConnections } from "./connection_config";
+import { UnsupportedCatalogFormatError } from "../errors";
 import { EnvironmentStore } from "./environment_store";
 
 type ApiConnection = components["schemas"]["Connection"];
@@ -1337,6 +1346,367 @@ describe("connection integration tests", () => {
                   /DuckLake connection configuration is missing/,
                );
             });
+
+            // ── catalog.metadataSchema ──────────────────────────────────────
+            //
+            // Several independent DuckLake catalogs may share ONE catalog
+            // database when each attaches its own metadata schema. These use a
+            // LOCAL directory as DATA_PATH rather than S3/GCS, so they need only
+            // the Postgres service and are not skipped for want of object-store
+            // credentials.
+            describe("catalog.metadataSchema", () => {
+               const pgCatalog = () => ({
+                  host: process.env.POSTGRES_TEST_HOST,
+                  port: parseInt(process.env.POSTGRES_TEST_PORT || "5432"),
+                  userName: process.env.POSTGRES_TEST_USER!,
+                  password: process.env.POSTGRES_TEST_PASSWORD!,
+                  databaseName: process.env.POSTGRES_TEST_DATABASE,
+               });
+
+               const pgConnString = () => {
+                  const pg = pgCatalog();
+                  return (
+                     `host=${pg.host} port=${pg.port} user=${pg.userName} ` +
+                     `password=${pg.password}` +
+                     (pg.databaseName ? ` dbname=${pg.databaseName}` : "")
+                  );
+               };
+
+               // A unique schema per test AND per run: the catalog database is
+               // shared across the specs in this file, and (locally) across runs,
+               // so a fixed name would let one test observe another's metadata.
+               const runId = Math.random().toString(36).slice(2, 8);
+               let schemaSeq = 0;
+               const createdSchemas: string[] = [];
+               const uniqueSchema = (label: string) => {
+                  const schema = `dl_meta_${label}_${runId}_${++schemaSeq}`;
+                  createdSchemas.push(schema);
+                  return schema;
+               };
+
+               // Leave the catalog database as we found it. These schemas are
+               // created by DuckLake inside a database shared with the other
+               // specs in this file, and enough of them makes a sibling test's
+               // schema enumeration miss `public`.
+               afterAll(async () => {
+                  if (
+                     !hasPostgresCredentials() ||
+                     createdSchemas.length === 0
+                  ) {
+                     return;
+                  }
+                  const workDir = await fs.mkdtemp(
+                     path.join(os.tmpdir(), "dl-cleanup-"),
+                  );
+                  const conn = new DuckDBConnection(
+                     "dl_cleanup",
+                     ":memory:",
+                     workDir,
+                  );
+                  try {
+                     await conn.runSQL(`INSTALL postgres`);
+                     await conn.runSQL(`LOAD postgres`);
+                     await conn.runSQL(
+                        `ATTACH '${pgConnString()}' AS cleanup (TYPE postgres);`,
+                     );
+                     for (const schema of createdSchemas) {
+                        // Quoted, because at least one test registers a mixed-case
+                        // schema and an unquoted identifier would not match it. And
+                        // reported rather than swallowed: a silently failing drop
+                        // leaks one schema per run into the shared catalog database,
+                        // which is the accumulation this hook exists to prevent.
+                        await conn
+                           .runSQL(`DROP SCHEMA cleanup."${schema}" CASCADE;`)
+                           .catch((error: unknown) =>
+                              console.warn(
+                                 `Failed to drop test schema "${schema}":`,
+                                 error,
+                              ),
+                           );
+                     }
+                  } catch (error) {
+                     console.warn("DuckLake schema cleanup failed:", error);
+                  } finally {
+                     await conn.close().catch(() => undefined);
+                  }
+               });
+
+               const duckLakeConfig = async (
+                  name: string,
+                  metadataSchema?: string,
+               ) => {
+                  const dataDir = path.join(
+                     testEnvironmentPath,
+                     `${name}_data`,
+                  );
+                  await fs.mkdir(dataDir, { recursive: true });
+                  return {
+                     catalog: {
+                        postgresConnection: pgCatalog(),
+                        ...(metadataSchema ? { metadataSchema } : {}),
+                     },
+                     storage: { bucketUrl: `${dataDir}/` },
+                  } as components["schemas"]["DucklakeConnection"];
+               };
+
+               // Bootstrap a catalog the way a BUILD does — a read-WRITE attach.
+               // The read-only serve attach cannot create one ("creating a new
+               // DuckLake is explicitly disabled"), so anything exercising the
+               // serve path needs this first. Also the natural place to assert
+               // that the build path carries METADATA_SCHEMA.
+               const bootstrapCatalog = async (
+                  dbName: string,
+                  cfg: components["schemas"]["DucklakeConnection"],
+               ): Promise<DuckDBConnection> => {
+                  const workDir = await fs.mkdtemp(
+                     path.join(os.tmpdir(), `dl-boot-${dbName}-`),
+                  );
+                  const conn = new DuckDBConnection(
+                     `bootstrap_${dbName}`,
+                     ":memory:",
+                     workDir,
+                  );
+                  createdConnections.push(conn);
+                  await attachDuckLakeReadWrite(conn, dbName, cfg);
+                  return conn;
+               };
+
+               const connect = async (defs: ApiConnection[]) => {
+                  const { malloyConnections } =
+                     await createEnvironmentConnections(
+                        defs,
+                        testEnvironmentPath,
+                     );
+                  const out = new Map<string, DuckDBConnection>();
+                  for (const def of defs) {
+                     const c = malloyConnections.get(
+                        def.name!,
+                     ) as DuckDBConnection;
+                     createdConnections.push(c);
+                     out.set(def.name!, c);
+                  }
+                  return out;
+               };
+
+               const firstValue = (rows: Record<string, unknown>[]) =>
+                  Number(Object.values(rows[0])[0]);
+
+               it(
+                  "puts DuckLake metadata in the configured schema, creating it",
+                  async () => {
+                     if (!hasPostgresCredentials()) {
+                        console.log("Skipping: PostgreSQL not configured");
+                        return;
+                     }
+                     const schema = uniqueSchema("lands");
+                     const cfg = await duckLakeConfig("dl_lands", schema);
+                     const c = await bootstrapCatalog("dl_lands", cfg);
+                     await c.runSQL(
+                        `CREATE OR REPLACE TABLE dl_lands.t AS SELECT 1 AS x`,
+                     );
+
+                     // Read the catalog database directly: the ducklake_*
+                     // bookkeeping tables must be in `schema`, which DuckLake
+                     // created on attach (this test never created the schema).
+                     await c.runSQL(
+                        `ATTACH '${pgConnString()}' AS insp (TYPE postgres, READ_ONLY);`,
+                     );
+                     const found = await c.runSQL(
+                        `SELECT count(*) AS n FROM insp.${schema}.ducklake_metadata;`,
+                     );
+                     expect(firstValue(found.rows)).toBeGreaterThan(0);
+                  },
+                  { timeout: 60000 },
+               );
+
+               it(
+                  "isolates two catalogs sharing one catalog database",
+                  async () => {
+                     if (!hasPostgresCredentials()) {
+                        console.log("Skipping: PostgreSQL not configured");
+                        return;
+                     }
+                     const a = await bootstrapCatalog(
+                        "dl_a",
+                        await duckLakeConfig("dl_a", uniqueSchema("a")),
+                     );
+                     const b = await bootstrapCatalog(
+                        "dl_b",
+                        await duckLakeConfig("dl_b", uniqueSchema("b")),
+                     );
+
+                     await a.runSQL(
+                        `CREATE OR REPLACE TABLE dl_a.only_in_a AS SELECT 1`,
+                     );
+                     await b.runSQL(
+                        `CREATE OR REPLACE TABLE dl_b.only_in_b AS SELECT 2`,
+                     );
+
+                     const tablesOf = async (
+                        conn: DuckDBConnection,
+                        db: string,
+                     ) => {
+                        const r = await conn.runSQL(
+                           `SELECT table_name FROM duckdb_tables() WHERE database_name = '${db}';`,
+                        );
+                        return r.rows.map((row) => Object.values(row)[0]);
+                     };
+
+                     // Each catalog sees its own table and NOT the other's —
+                     // the whole point of a per-catalog metadata schema. Both
+                     // live in ONE catalog database.
+                     expect(await tablesOf(a, "dl_a")).toEqual(["only_in_a"]);
+                     expect(await tablesOf(b, "dl_b")).toEqual(["only_in_b"]);
+                  },
+                  { timeout: 60000 },
+               );
+
+               it(
+                  "serves read-only from a catalog in a non-default schema",
+                  async () => {
+                     if (!hasPostgresCredentials()) {
+                        console.log("Skipping: PostgreSQL not configured");
+                        return;
+                     }
+                     // The read-only serve attach must pass METADATA_SCHEMA too:
+                     // without it the attach looks in the catalog's default
+                     // schema, finds nothing, and fails outright, because a
+                     // read-only attach may not create a catalog.
+                     const schema = uniqueSchema("serve");
+                     const cfg = await duckLakeConfig("dl_serve", schema);
+                     const boot = await bootstrapCatalog("dl_serve", cfg);
+                     await boot.runSQL(
+                        `CREATE OR REPLACE TABLE dl_serve.t AS SELECT 7 AS x`,
+                     );
+
+                     const conns = await connect([
+                        {
+                           name: "dl_serve",
+                           type: "ducklake",
+                           ducklakeConnection: cfg,
+                        } as ApiConnection,
+                     ]);
+                     const served = conns.get("dl_serve")!;
+                     const r = await served.runSQL(`SELECT x FROM dl_serve.t;`);
+                     expect(firstValue(r.rows)).toBe(7);
+                  },
+                  { timeout: 60000 },
+               );
+
+               it(
+                  "keeps the catalog-format preflight working for a non-default schema",
+                  async () => {
+                     if (!hasPostgresCredentials()) {
+                        console.log("Skipping: PostgreSQL not configured");
+                        return;
+                     }
+                     // The preflight reads `ducklake_metadata`, which lives in
+                     // the configured schema. Read unqualified it would MISS,
+                     // and the preflight fails SOFT (logs and returns) — so the
+                     // range check would silently stop protecting exactly the
+                     // catalogs setting this option. Poisoning the recorded
+                     // version proves the read resolves: an unqualified read
+                     // finds nothing and so raises nothing.
+                     const schema = uniqueSchema("preflight");
+                     const cfg = await duckLakeConfig("dl_pf", schema);
+                     const boot = await bootstrapCatalog("dl_pf", cfg);
+                     await boot.runSQL(
+                        `ATTACH '${pgConnString()}' AS poison (TYPE postgres);`,
+                     );
+                     await boot.runSQL(
+                        `UPDATE poison.${schema}.ducklake_metadata ` +
+                           `SET value = '9999.0' WHERE key = 'version';`,
+                     );
+
+                     // A fresh attach of the same catalog must now refuse with
+                     // the clean typed range error rather than proceeding.
+                     let err: unknown;
+                     try {
+                        await bootstrapCatalog("dl_pf_again", cfg);
+                     } catch (e) {
+                        err = e;
+                     }
+                     // The TYPE matters: converting a deep DuckDB failure into
+                     // this typed refusal is the preflight's whole job, so a
+                     // message match alone could not tell the two apart.
+                     expect(err).toBeInstanceOf(UnsupportedCatalogFormatError);
+                     // And it must be THIS catalog's poisoned format. Asserting
+                     // the value keeps the test honest if some other schema in
+                     // the shared catalog database holds a valid catalog: an
+                     // unqualified read would report that one's format instead,
+                     // which is exactly the bug being guarded against.
+                     expect((err as Error).message).toContain("9999.0");
+                  },
+                  { timeout: 60000 },
+               );
+
+               it(
+                  "round-trips a mixed-case metadataSchema through the preflight",
+                  async () => {
+                     if (!hasPostgresCredentials()) {
+                        console.log("Skipping: PostgreSQL not configured");
+                        return;
+                     }
+                     // The validator accepts mixed case but nothing exercised it, so
+                     // this covers the create -> preflight -> attach round-trip for
+                     // such a name. Honest scope: it does NOT discriminate on the
+                     // preflight's identifier quoting — measured, unquoted resolves
+                     // too, because DuckDB matches identifiers case-insensitively.
+                     // Poisoning the version is what proves the preflight read THIS
+                     // catalog's metadata rather than missing silently.
+                     const schema = `DlMixedCase_${runId}`;
+                     createdSchemas.push(schema);
+                     const cfg = await duckLakeConfig("dl_mixed", schema);
+                     const boot = await bootstrapCatalog("dl_mixed", cfg);
+                     await boot.runSQL(
+                        `ATTACH '${pgConnString()}' AS poison_mixed (TYPE postgres);`,
+                     );
+                     await boot.runSQL(
+                        `UPDATE poison_mixed."${schema}".ducklake_metadata ` +
+                           `SET value = '9999.0' WHERE key = 'version';`,
+                     );
+
+                     let err: unknown;
+                     try {
+                        await bootstrapCatalog("dl_mixed_again", cfg);
+                     } catch (e) {
+                        err = e;
+                     }
+                     expect(err).toBeInstanceOf(UnsupportedCatalogFormatError);
+                     expect((err as Error).message).toContain("9999.0");
+                  },
+                  { timeout: 60000 },
+               );
+
+               it(
+                  "attaches without a metadataSchema exactly as before",
+                  async () => {
+                     if (!hasPostgresCredentials()) {
+                        console.log("Skipping: PostgreSQL not configured");
+                        return;
+                     }
+                     // Back-compat: the option is a conditional append, so an
+                     // absent value emits the pre-existing ATTACH verbatim and
+                     // DuckLake uses the catalog connection's default schema.
+                     const cfg = await duckLakeConfig("dl_default");
+                     const c = await bootstrapCatalog("dl_default", cfg);
+                     await c.runSQL(
+                        `CREATE OR REPLACE TABLE dl_default.t AS SELECT 7 AS x`,
+                     );
+                     const r = await c.runSQL(`SELECT x FROM dl_default.t;`);
+                     expect(firstValue(r.rows)).toBe(7);
+
+                     await c.runSQL(
+                        `ATTACH '${pgConnString()}' AS insp2 (TYPE postgres, READ_ONLY);`,
+                     );
+                     const inPublic = await c.runSQL(
+                        `SELECT count(*) AS n FROM insp2.public.ducklake_metadata;`,
+                     );
+                     expect(firstValue(inPublic.rows)).toBeGreaterThan(0);
+                  },
+                  { timeout: 60000 },
+               );
+            });
          });
 
          it("should throw error if DuckDB connection name conflicts with attached database", async () => {

package/src/service/connection.ts

@@ -477,33 +477,72 @@ function runSQLRows(result: unknown): Record<string, unknown>[] {
  * the fixed name (which would make every later preflight for this connection
  * fail its ATTACH with "already exists" and silently skip), and so two
  * concurrent first-touch lookups can't cross-DETACH each other.
+ *
+ * {@link metadataSchema} must be the catalog's configured
+ * `catalog.metadataSchema`, because `ducklake_metadata` lives in that schema
+ * rather than the catalog connection's default one. Getting this wrong is not
+ * loud: the read would simply miss, the catch below would log and return, and the
+ * range check would stop protecting precisely the catalogs that set the option.
  */
 let ducklakePreflightSeq = 0;
 async function preflightDuckLakeCatalogFormat(
    connection: DuckDBConnection,
    dbName: string,
    pgConnString: string,
+   metadataSchema?: string,
 ): Promise<void> {
    const tempDb = `${dbName}_fmt_preflight_${++ducklakePreflightSeq}`;
+   // Identifier position, not a string literal, so the schema is double-quoted.
+   // Measured: with today's validator this is belt-and-braces rather than a fix —
+   // every name the regex admits resolves correctly unquoted, including reserved
+   // words (DuckDB parses them fine here) and mixed case (matching is
+   // case-insensitive). It is quoted anyway because this preflight fails SOFT: a
+   // read that misses logs and returns, silently disabling format range-checking
+   // for that connection, so the cost of ever getting this wrong is invisible.
+   // Quoting makes correctness local to this line instead of contingent on the
+   // validator's accept-set, so widening that regex later cannot break it. Safe
+   // by construction: the regex admits no quote character to break out with.
+   const metadataRef = metadataSchema
+      ? `${tempDb}."${metadataSchema}".ducklake_metadata`
+      : `${tempDb}.ducklake_metadata`;
    let catalogFormat: string | undefined;
    try {
       await connection.runSQL(
          `ATTACH '${escapeSQL(pgConnString)}' AS ${tempDb} (TYPE postgres, READ_ONLY);`,
       );
       const result = await connection.runSQL(
-         `SELECT value FROM ${tempDb}.ducklake_metadata WHERE key = 'version' LIMIT 1;`,
+         `SELECT value FROM ${metadataRef} WHERE key = 'version' LIMIT 1;`,
       );
       const value = runSQLRows(result)[0]?.value;
       catalogFormat = typeof value === "string" ? value : undefined;
    } catch (error) {
+      const message = redactPgSecrets(
+         error instanceof Error ? error.message : String(error),
+      );
+      // A named metadata schema holding no catalog has two very different causes,
+      // and the preflight cannot tell them apart: it is the NORMAL state before the
+      // first read-write attach creates the catalog, and it is also what a typo (or
+      // adding `metadataSchema` to a catalog whose metadata lives elsewhere) looks
+      // like. Neither is loud on its own — a read-write attach CREATES an empty
+      // catalog there and materializes into it, and a read-only attach fails with an
+      // error that says nothing about the schema — so name the schema and say both,
+      // rather than implying a mistake on a path that is expected to hit this once
+      // per catalog. The message also has to hedge on the cause: `does not exist`
+      // matches a missing database or role too, not only a missing table.
+      if (metadataSchema !== undefined && /does not exist/i.test(message)) {
+         logger.warn(
+            "No DuckLake catalog found in the configured metadata schema. This is " +
+               "expected the first time a catalog is created there: a read-write " +
+               "attach will create it, and a read-only attach will fail until it " +
+               "exists. Otherwise check the schema name, and the catalog database " +
+               "and role, against the error.",
+            { dbName, metadataSchema, error: message },
+         );
+         return;
+      }
       logger.warn(
          "DuckLake catalog-format preflight read failed; falling back to ATTACH",
-         {
-            dbName,
-            error: redactPgSecrets(
-               error instanceof Error ? error.message : String(error),
-            ),
-         },
+         { dbName, error: message },
       );
       return;
    } finally {
@@ -633,21 +672,45 @@ async function attachDuckLakeWithMode(
    const mode = options.readOnly ? "READ_ONLY" : "READ_WRITE";
    // READ_ONLY: the client manages metadata, we only read the catalog.
    // READ_WRITE (build only): a build-scoped session materializes into it.
-   logger.info(`pgConnString: ${redactPgSecrets(pgConnString)}`);
+   // Debug, not info. These three lines — this one, the escaped form below, and the
+   // assembled ATTACH — are per-attach diagnostics that between them print the catalog
+   // host and database twice and the storage path once. `redactPgSecrets` removes the
+   // password and any URI userinfo, but a DATA_PATH is not a secret it knows about, so
+   // logging the assembled command at info discloses the bucket and whatever the prefix
+   // encodes to every reader of the logs. What an operator watching a healthy fleet
+   // needs is the mode and the outcome, which stay at info below.
+   logger.debug(`pgConnString: ${redactPgSecrets(pgConnString)}`);
    const escapedPgConnString = escapeSQL(pgConnString);
-   logger.info(
+   logger.debug(
       `Final escaped connection string: ${redactPgSecrets(escapedPgConnString)}`,
    );
    const escapedBucketUrl = escapeSQL(ducklakeConfig.storage.bucketUrl);
-   logger.info(`escapedBucketUrl: ${escapedBucketUrl}`);
+   // Optional metadata schema: which schema in the catalog database holds this
+   // DuckLake's `ducklake_*` tables. Absent keeps DuckLake's default (the catalog
+   // connection's default schema), so the emitted command is unchanged for every
+   // existing config. Validated to a plain identifier at config load, because it
+   // reaches a quoted literal here and an identifier position in the preflight.
+   const metadataSchema = ducklakeConfig.catalog.metadataSchema;
    // Range-preflight the catalog's recorded format version so an unsupported
-   // catalog fails as a clean, actionable 422 rather than a deep DuckDB 500.
-   await preflightDuckLakeCatalogFormat(connection, dbName, pgConnString);
+   // catalog fails as a clean, actionable 422 rather than a deep DuckDB 500. The
+   // schema must be threaded through: the preflight reads `ducklake_metadata`, so
+   // when the metadata does not live in the catalog's default schema an unqualified
+   // read misses it — and the preflight fails SOFT (logs and returns), so the range
+   // check would silently stop protecting exactly the catalogs using this option.
+   await preflightDuckLakeCatalogFormat(
+      connection,
+      dbName,
+      pgConnString,
+      metadataSchema,
+   );
    // READ_ONLY is stated explicitly; read-write omits the flag (DuckLake's
    // default is writable). AUTOMATIC_MIGRATION is never set in either mode.
    const readOnlyClause = options.readOnly ? ", READ_ONLY true" : "";
-   const attachCommand = `ATTACH OR REPLACE 'ducklake:postgres:${escapedPgConnString}' AS ${dbName} (DATA_PATH '${escapedBucketUrl}', OVERRIDE_DATA_PATH true${readOnlyClause});`;
-   logger.info(
+   const metadataSchemaClause = metadataSchema
+      ? `, METADATA_SCHEMA '${escapeSQL(metadataSchema)}'`
+      : "";
+   const attachCommand = `ATTACH OR REPLACE 'ducklake:postgres:${escapedPgConnString}' AS ${dbName} (DATA_PATH '${escapedBucketUrl}', OVERRIDE_DATA_PATH true${readOnlyClause}${metadataSchemaClause});`;
+   logger.debug(
       `Attaching DuckLake database using command: ${redactPgSecrets(attachCommand)}`,
    );
    try {

package/src/service/connection_config.spec.ts

@@ -671,4 +671,64 @@ describe("ducklake shape validation", () => {
          /Storage bucketUrl is required for DuckLake/i,
       );
    });
+
+   // metadataSchema reaches TWO grammars: a quoted string literal in the ATTACH,
+   // and a quoted identifier in the catalog-format preflight's table reference.
+   // Restricting it to a plain identifier at load is what keeps one value valid in
+   // both, so these pin the accept/reject boundary rather than trusting escaping.
+   const withSchema = (metadataSchema: unknown): ApiConnection =>
+      ({
+         ...valid,
+         ducklakeConnection: {
+            ...valid.ducklakeConnection,
+            catalog: {
+               ...valid.ducklakeConnection!.catalog,
+               metadataSchema,
+            },
+         },
+      }) as ApiConnection;
+
+   it("accepts an absent metadataSchema", () => {
+      // Optional: absence keeps DuckLake's default schema, the prior behavior.
+      expect(() =>
+         assembleEnvironmentConnections([valid], "/tmp/env"),
+      ).not.toThrow();
+   });
+
+   it("accepts a plain identifier metadataSchema", () => {
+      for (const ok of ["org_a", "_private", "Lake1", "a"]) {
+         expect(() =>
+            assembleEnvironmentConnections([withSchema(ok)], "/tmp/env"),
+         ).not.toThrow();
+      }
+   });
+
+   it("rejects a metadataSchema that is not a plain identifier", () => {
+      for (const bad of [
+         "foo'; DROP TABLE x; --",
+         "has space",
+         "dotted.name",
+         "1leading_digit",
+         "",
+         '"quoted"',
+      ]) {
+         expect(() =>
+            assembleEnvironmentConnections([withSchema(bad)], "/tmp/env"),
+         ).toThrow(/metadataSchema must be a plain identifier/i);
+      }
+   });
+
+   it("rejects a non-string metadataSchema rather than coercing it", () => {
+      // The value comes from untyped JSON and RegExp.test() coerces, so `true` and
+      // `null` match the identifier pattern as "true"/"null" and would pass a
+      // pattern-only check — then reach escapeSQL's String.replace as a non-string
+      // and throw TypeError at the connection's first attach. That runtime failure is
+      // the thing this load-time check exists to prevent, so the type is part of the
+      // contract, not a formality.
+      for (const bad of [true, false, 0, 1, null, {}, [], ["org_a"]]) {
+         expect(() =>
+            assembleEnvironmentConnections([withSchema(bad)], "/tmp/env"),
+         ).toThrow(/metadataSchema must be a plain identifier/i);
+      }
+   });
 });