@google-cloud/kcmd 0.0.0-stage → 0.2.0

package/build/ts/kcmd/semantic/bigquery.js

@@ -0,0 +1,469 @@
+"use strict";
+// Generates BigQuery property-graph DDL (with inline measures) from the
+// Semantic Model IR.
+//
+// The shared GoogleSQL generator (./graph_ddl) writes the graph structure: node
+// tables, edge tables, labels, properties, and key and join columns. This
+// module supplies its BigQuery engine: qualified names, measures, the
+// per-element OPTIONS clause, and the SQL text a field binds to.
+//
+// BigQuery graph measures bind an aggregate to exactly one table's KEY; the
+// cross-entity rollup happens at query time via GRAPH_EXPAND(...) + AGG(...).
+// A metric therefore lands on whichever single table its aggregate columns
+// reference; a metric whose aggregate genuinely spans multiple tables cannot be
+// expressed as one MEASURE and is skipped (reported in `warnings`).
+//
+// A measure can only aggregate an EXPOSED PROPERTY of its node (not a raw
+// column or an inline expression), so each metric is lowered into a derived
+// operand property plus a MEASURE over it (see placeMetric / exposeOperand).
+//
+// See: https://docs.cloud.google.com/bigquery/docs/graph-measures
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePropertyGraph = generatePropertyGraph;
+exports.elementDescription = elementDescription;
+exports.fieldDescription = fieldDescription;
+const graph_ddl_1 = require("./graph_ddl");
+const ir_1 = require("./ir");
+const sql_expr_utils_1 = require("./sql_expr_utils");
+const sql_identifiers_1 = require("./sql_identifiers");
+const sql_parser_1 = require("./sql_parser");
+/**
+ * Generates the BigQuery property-graph DDL for a semantic model.
+ *
+ * The generated statement references the entities' existing base tables; it
+ * does not create them. Returns the DDL plus any warnings collected while
+ * mapping the IR (e.g. metrics that could not be placed on a single table).
+ *
+ * Throws when the model yields no valid node table -- it declares no entities,
+ * or every entity lacks a KEY -- since a property graph with an empty NODE
+ * TABLES block is invalid DDL that BigQuery would reject.
+ */
+function generatePropertyGraph(model, opts = {}) {
+    return (0, graph_ddl_1.generateGraphDdl)(model, bigQueryEngine(opts));
+}
+// The BigQuery engine for the shared generator.
+function bigQueryEngine(opts) {
+    return {
+        name: 'BigQuery',
+        table: qualifyTable,
+        graphName: model => qualifyGraph(model, opts),
+        placeMetrics,
+        elementOptions: (description, ai) => optionsClause(elementDescription(description, ai), ai?.synonyms),
+        fieldOptions: field => optionsClause(fieldDescription(field), field.aiContext?.synonyms),
+        dialect: 'BIGQUERY',
+        fieldExpression,
+    };
+}
+// Places each metric on the single entity its aggregate references, lowering
+// it to a MEASURE over an exposed property (see placeMetric).
+function placeMetrics(metrics, input, warnings) {
+    const loweringByEntity = new Map();
+    const metricNames = new Set(metrics.map(m => m.name));
+    for (const metric of metrics) {
+        placeMetric(metric, input, metricNames, loweringByEntity, warnings);
+    }
+    // The operand properties come first: the measures aggregate them.
+    const placed = new Map();
+    for (const [name, lowering] of loweringByEntity) {
+        placed.set(name, [...lowering.derivedProperties, ...lowering.measures]);
+    }
+    return placed;
+}
+// Builds the lowering state for an entity, seeded with its declared fields so
+// an operand with the same SQL as a field reuses that property instead of
+// duplicating it. A field the node table leaves out has no property to reuse,
+// and neither has an ambiguous one.
+//
+// A field is ambiguous when the node's table has a column of its name that the
+// field does not read whole, such as `amount` bound to `amount_usd` while
+// `amount_local` is bound to the column `amount`. A measure that names it
+// names both, and BigQuery rejects the graph: "Name amount is ambiguous
+// because it exists as both a column and a graph property". The columns the
+// table is known to have are its key columns and those the fields' SQL reads.
+function newLowering(entity, input, metricNames) {
+    const taken = new Set();
+    const sqlOf = new Map();
+    for (const f of entity.fields) {
+        taken.add(f.name);
+        const read = input.renderedFieldSql(entity, f);
+        if ('sql' in read)
+            sqlOf.set(f.name, read.sql);
+    }
+    const columns = new Set((0, graph_ddl_1.nodeKey)(entity).map(k => k.replace(/^`(.*)`$/, '$1').toLowerCase()));
+    for (const sql of sqlOf.values()) {
+        // The SQL is local to the table, so `a.b` reads the column `a`.
+        for (const c of (0, sql_expr_utils_1.columnReferences)((0, sql_identifiers_1.quoteIfReserved)(sql), 'BIGQUERY') ?? []) {
+            columns.add((c.qualifier ?? c.name).toLowerCase());
+        }
+    }
+    const ambiguous = new Set();
+    const byLocalExpr = new Map();
+    for (const [name, sql] of sqlOf) {
+        if (columns.has(name.toLowerCase()) &&
+            loneColumn(sql)?.toLowerCase() !== name.toLowerCase()) {
+            ambiguous.add(name);
+        }
+        else if (!byLocalExpr.has(sql)) {
+            byLocalExpr.set(sql, name);
+        }
+    }
+    return {
+        derivedProperties: [],
+        measures: [],
+        taken,
+        metricNames,
+        ambiguous,
+        byLocalExpr,
+        operandToName: new Map()
+    };
+}
+// The column `sql`, BigQuery SQL local to a table, is when it is one column of
+// that table and nothing else, without its quotes, as in `amount` or
+// `` `order` ``. Undefined otherwise.
+function loneColumn(sql) {
+    const column = (0, sql_parser_1.soleColumn)((0, sql_identifiers_1.quoteIfReserved)(sql), 'BIGQUERY');
+    return column && column.qualifier === undefined ? column.name : undefined;
+}
+// Assigns a metric to the node table of the single entity its aggregate
+// references, lowering it to a MEASURE over an exposed property. Records a
+// warning (and skips) when it references zero/multiple entities or is not a
+// single supported aggregate over one operand.
+function placeMetric(metric, input, metricNames, loweringByEntity, warnings) {
+    const { entityByName, skipped, ancestorsUsed } = input;
+    // A measure is emitted from the metric's BigQuery SQL (see
+    // metricExpression). A metric with SQL only for other engines is skipped
+    // with a warning naming the dialects it lacks, rather than emitting that
+    // other engine's SQL into a BigQuery graph.
+    const expression = metricExpression(metric);
+    if (expression === undefined) {
+        warnings.push(metric.dialects?.length || metric.importedExpression !== undefined ?
+            `metric '${metric.name}' has no 'BIGQUERY' or 'ANSI_SQL' ` +
+                `expression; skipped (nothing to emit as a MEASURE)` :
+            `metric '${metric.name}' has no expression; skipped (nothing ` +
+                `to emit as a MEASURE)`);
+        return;
+    }
+    // The entities whose qualifier the expression writes before a column, as
+    // the SQL parser reads it (see measureEntities), so neither a value like
+    // 'orders.x' nor a function namespace such as `NET.` in `NET.HOST(...)`
+    // references an entity. A qualifier-free aggregate (e.g. COUNT(*)) names no
+    // entity in its expression; it falls back to `metric.entity` when the IR
+    // provides one (an authored `entity` in `0.2.0.dev0/google`, an entity
+    // inferred from another dialect entry, or hand-built IR), so it can still be
+    // placed rather than dropped as "references no entity".
+    const referenced = (0, sql_expr_utils_1.measureEntities)(expression, [...entityByName.keys()], metric.entity);
+    if (referenced.length !== 1) {
+        const detail = referenced.length === 0 ?
+            'references no known entity' :
+            `spans multiple tables (${referenced.join(', ')})`;
+        warnings.push(`metric '${metric.name}' ${detail}; skipped (cannot be a single MEASURE)`);
+        return;
+    }
+    const entityName = referenced[0];
+    // The IR also declares a single attach entity (metric.entity). Placement is
+    // driven by the qualifiers actually present in the expression (that is what
+    // we strip and attach), but a disagreement with the declared entity signals
+    // an inconsistent model, so surface it. Emit this only now that we know the
+    // metric will actually be placed, so a metric that is subsequently dropped
+    // does not carry a contradictory "placing per the expression" note.
+    if (metric.entity && entityName !== metric.entity) {
+        warnings.push(`metric '${metric.name}' declares entity '${metric.entity}' but its ` +
+            `expression references '${entityName}'; placing per the expression`);
+    }
+    const entity = entityByName.get(entityName);
+    if (!entity) {
+        warnings.push(`metric '${metric.name}' references unknown entity '${entityName}'; skipped (cannot be a single MEASURE)`);
+        return;
+    }
+    // An abstract entity is a table-less supertype with no node table, so it can
+    // carry no MEASURE. Report that specifically -- it is also in `skipped`, so
+    // this must precede the generic no-KEY message below to stay accurate.
+    if (entity.abstract) {
+        warnings.push(`metric '${metric.name}' targets entity '${entityName}', which is ` +
+            `abstract (a table-less supertype with no node table to carry a ` +
+            `MEASURE); metric dropped`);
+        return;
+    }
+    // A metric can only become a MEASURE on a node table, but an entity that was
+    // skipped upstream (empty KEY) has no node table to carry it. Check the skip
+    // set already computed, and report the drop directly, instead of letting it
+    // fail later with a misleading "aggregate not supported" message.
+    if (skipped.has(entityName)) {
+        warnings.push(`metric '${metric.name}' targets entity '${entityName}', which has no KEY and was skipped; metric dropped`);
+        return;
+    }
+    // A measure is allowed only on a LEAF type -- one that no table-emitting
+    // entity extends. A metric lowers to a MEASURE on the target's DEFAULT LABEL;
+    // when that entity is a supertype its label is shared with every subtype
+    // table, and BigQuery forbids a MEASURE on a label carried by more than one
+    // element table (verified live: "defined as MEASURE, but there are other
+    // declarations with the same name"). Drop it with a warning rather than emit
+    // DDL BigQuery rejects. Push validation rejects such a metric before
+    // generation; this guard covers a caller that generates DDL without
+    // validating first.
+    if (ancestorsUsed.has(entityName)) {
+        warnings.push(`metric '${metric.name}' targets entity '${entityName}', which is not ` +
+            `a leaf type (another entity extends it); a measure is allowed only on ` +
+            `a leaf type, because a supertype's label is shared across its ` +
+            `subtype tables; skipped`);
+        return;
+    }
+    const body = (0, sql_expr_utils_1.withoutQualifier)(expression, entityName);
+    // A graph measure must be one supported aggregate wrapping a single operand;
+    // anything else (a non-aggregate, or a compound of aggregates like a ratio)
+    // cannot be a single MEASURE. Flag it rather than emit DDL BigQuery rejects.
+    // The SQL parser finds the aggregate and its operand with the entity's
+    // qualifier renamed to a name it does not reserve, since it cannot read one
+    // it reserves, as in `SUM(Date.days)`.
+    const stand = (0, sql_expr_utils_1.unusedName)(expression, 'kcmd_entity');
+    const agg = (0, sql_expr_utils_1.singleAggregate)((0, sql_expr_utils_1.requalified)(expression, entityName, stand), 'BIGQUERY');
+    if (!agg) {
+        warnings.push(`metric '${metric.name}' expression '${body}' is not a single supported aggregate ` +
+            `(${sql_expr_utils_1.SUPPORTED_AGGREGATES.join(', ')}) over one operand; skipped (cannot be a single MEASURE)`);
+        return;
+    }
+    const lowering = loweringByEntity.get(entityName) ??
+        newLowering(entity, input, metricNames);
+    loweringByEntity.set(entityName, lowering);
+    // Resolve the aggregate's operand to an exposed property. It is read as
+    // written, qualifiers kept, so readOperand can tell the entity's fields from
+    // its columns. COUNT(*) has no operand column, so it counts the first column
+    // of the node's key instead: the primary key, else the first unique key
+    // (nodeKey). singleAggregate gives a `*` operand for COUNT(*) alone.
+    const operand = (0, sql_expr_utils_1.requalified)(agg.operand, stand, entityName);
+    let read;
+    if (operand === '*') {
+        // A key names a column, never a field, so a field of the same name does
+        // not stand in for it. A simple name is quoted, if reserved, where it is
+        // exposed (exposeOperand).
+        const key = (0, graph_ddl_1.nodeKey)(entity)[0];
+        read = {
+            sql: (0, sql_identifiers_1.isSimpleIdentifier)(key) ? key : (0, graph_ddl_1.physicalColumn)(key),
+            column: true
+        };
+    }
+    else {
+        // A field the node table leaves out declares no property, so neither a
+        // measure over it nor a property derived from SQL that names it can read
+        // it.
+        read = readOperand(entity, operand, input);
+    }
+    if ('skip' in read) {
+        warnings.push(`metric '${metric.name}' ${read.skip}; skipped (nothing to emit as a ` +
+            `MEASURE)`);
+        return;
+    }
+    // The measure is itself exposed as a node property named `metric.name`, so it
+    // must not collide with a field, a prior measure, or a synthesized operand
+    // property — a duplicate property makes BigQuery reject the whole node table.
+    // A clash with an already-taken name is a model error we cannot paper over by
+    // renaming (the measure name is exactly what a reader selects via
+    // GRAPH_EXPAND + AGG(<label>_<name>)), so skip + warn. Reserve it up front so
+    // the operand lowering below never synthesizes a property with the same name.
+    if (lowering.taken.has(metric.name)) {
+        warnings.push(`metric '${metric.name}' collides with an existing property of entity ` +
+            `'${entityName}'; skipped (rename the metric to avoid a duplicate graph property)`);
+        return;
+    }
+    lowering.taken.add(metric.name);
+    const propName = exposeOperand(lowering, read, metric.name);
+    const aggregate = `${agg.fn}(${agg.distinct ? 'DISTINCT ' : ''}${(0, sql_identifiers_1.quoteIfReserved)(propName)})`;
+    const opts = optionsClause(elementDescription(metric.description, metric.aiContext), metric.aiContext?.synonyms);
+    const measure = `MEASURE(${aggregate}) AS ${(0, sql_identifiers_1.quoteIfReserved)(metric.name)}`;
+    lowering.measures.push(opts ? `${measure} ${opts}` : measure);
+}
+function readOperand(entity, operand, input) {
+    // Checked before any column: a field is read through its own SQL, which may
+    // name another column, while a column of the same name may hold something
+    // else. The SQL parser reads the entity's qualifier renamed, as placeMetric
+    // does, since it cannot read one it reserves, as in `Date.days`.
+    const stand = (0, sql_expr_utils_1.unusedName)(operand, 'kcmd_entity');
+    const column = (0, sql_parser_1.soleColumn)((0, sql_expr_utils_1.requalified)(operand, entity.name, stand), 'BIGQUERY');
+    const own = column !== undefined &&
+        (column.qualifier === undefined ||
+            column.qualifier.toLowerCase() === stand);
+    const field = own ? entity.fields.find(f => f.name === column.name) : undefined;
+    if (field) {
+        const read = input.renderedFieldSql(entity, field);
+        return 'sql' in read ?
+            { field: field.name, sql: read.sql, column: !!loneColumn(read.sql) } :
+            { skip: `aggregates ${read.reads}` };
+    }
+    const read = input.localSql(entity, operand);
+    return 'sql' in read ? { sql: read.sql, column: own } :
+        { skip: `reads ${read.reads}` };
+}
+// Ensures the operand `read` is exposed as a node property and returns its
+// property name. A field is one already, unless it is ambiguous (see
+// newLowering); its SQL is then exposed as any other SQL is. Other SQL reuses
+// a field (or a previously derived property) with the same SQL; a column no
+// field names is exposed under its own name; any other SQL gets a
+// synthesized, unique name derived from the metric.
+function exposeOperand(lowering, read, metricName) {
+    // A MEASURE may aggregate a field directly by name -- even when a profile
+    // bound that field to a differently named physical column (the property is
+    // `<column> AS <field>`, and a MEASURE may reference a sibling alias).
+    // Synthesizing an input property here would emit `<field> AS ..._input`, and
+    // an alias is illegal inside a property expression -- BigQuery rejects it with
+    // "Unrecognized name".
+    if (read.field !== undefined && !lowering.ambiguous.has(read.field)) {
+        return read.field;
+    }
+    const { sql } = read;
+    const existing = lowering.byLocalExpr.get(sql) ?? lowering.operandToName.get(sql);
+    if (existing)
+        return existing;
+    const isFree = (name) => !lowering.taken.has(name) && !lowering.metricNames.has(name);
+    let name;
+    if (read.column && (0, sql_identifiers_1.isSimpleIdentifier)(sql) && isFree(sql)) {
+        // A column not already declared: expose it under its own name.
+        name = sql;
+        lowering.derivedProperties.push((0, sql_identifiers_1.quoteIfReserved)(name));
+    }
+    else {
+        name = uniqueName(`${metricName}_input`, isFree);
+        // Only a column is quoted: a keyword such as TRUE stays a keyword.
+        lowering.derivedProperties.push(`${read.column ? (0, sql_identifiers_1.quoteIfReserved)(sql) : sql} AS ${name}`);
+    }
+    lowering.taken.add(name);
+    lowering.operandToName.set(sql, name);
+    return name;
+}
+// Returns `base` if free, else the first of `base_2`, `base_3`, ... that is.
+function uniqueName(base, isFree) {
+    if (isFree(base))
+        return base;
+    for (let i = 2;; i++) {
+        const candidate = `${base}_${i}`;
+        if (isFree(candidate))
+            return candidate;
+    }
+}
+// The SQL BigQuery runs for a field or metric: its `BIGQUERY` dialect entry,
+// else its `ANSI_SQL` one (see expressionForDialect), read as BigQuery with its
+// comments removed. Another engine's vendor SQL is never returned. The DDL puts
+// ` AS <name>` and a comma after the expression on the same line, and a line
+// comment left in would swallow them.
+function fieldExpression(f) {
+    return bigQuerySql(f);
+}
+function metricExpression(m) {
+    return bigQuerySql(m);
+}
+function bigQuerySql(item) {
+    const text = (0, ir_1.expressionForDialect)(item, 'BIGQUERY');
+    return text === undefined ? undefined : (0, sql_expr_utils_1.sqlWithoutComments)(text);
+}
+// Builds a backtick-quoted table reference from the IR's `dataSource` string.
+// The IR contract guarantees `dataSource` is already canonical and
+// fully-qualified: the producer (loader) normalizes a BigQuery or BigLake
+// source into a dotted `project.dataset.table` (or four-part BigLake catalog
+// name). For BigQuery that canonical form IS the target addressing scheme, so
+// this emits it verbatim and NEVER prepends the graph's own project/dataset --
+// those name where the graph is CREATED, not where a source table lives, and
+// the two can differ (e.g. a graph in `proj.demo` over source tables in
+// `samples.tpch`). Qualifying a source table is the producer's job, not the
+// emitter's.
+function qualifyTable(dataSource, warnings, context) {
+    const trimmed = (dataSource ?? '').trim();
+    if (!trimmed) {
+        warnings.push(`${context}: empty data source; the table reference will be invalid`);
+        return '``';
+    }
+    return `\`${trimmed}\``;
+}
+// Builds the dataset-qualified graph name, filling a missing project/dataset
+// from opts and then from the first entity's qualified dataSource.
+function qualifyGraph(model, opts) {
+    const name = opts.graphName ?? model.name;
+    let project = opts.project;
+    let dataset = opts.dataset;
+    // Pick the first entity with a non-empty `dataSource` to derive the graph's
+    // location; skip abstract entities (empty source).
+    const first = (model.entities ?? []).find(e => e.dataSource);
+    if ((!project || !dataset) && first) {
+        const p = first.dataSource.trim().split('.');
+        if (p.length >= 3) {
+            project = project ?? p[0];
+            dataset = dataset ?? p[1];
+        }
+        else if (p.length === 2) {
+            dataset = dataset ?? p[0];
+        }
+    }
+    // A graph name is `name`, `dataset.name`, or `project.dataset.name`; a
+    // project with no dataset cannot be expressed (`project.name` would be read
+    // as `dataset.name`), so drop a lone project rather than emit a malformed
+    // reference.
+    if (project && !dataset)
+        project = undefined;
+    const parts = [project, dataset, name].filter((p) => !!p);
+    return `\`${parts.join('.')}\``;
+}
+// Composes the folded `description` text for a graph element from its base
+// description and the AI-first annotations that have no dedicated BigQuery
+// option: instructions and examples. Synonyms are NOT folded in here --
+// BigQuery's PropertyGraph{Label,Property}Options carry a structured `synonyms`
+// array, so they are emitted as their own option (see optionsClause and the
+// call sites).
+function elementDescription(description, ai) {
+    return composeText([
+        description,
+        ai?.instructions,
+        examplesLine(ai?.examples),
+    ]);
+}
+// A field additionally carries a human `label` and a temporal-dimension role,
+// which lead the composed text (matching the authored order) ahead of its
+// description and instructions/examples. Synonyms are emitted structurally, as
+// for elementDescription.
+function fieldDescription(field) {
+    return composeText([
+        field.label,
+        (0, ir_1.isTimeDimension)(field) ? 'Time dimension.' : undefined,
+        field.description,
+        field.aiContext?.instructions,
+        examplesLine(field.aiContext?.examples),
+    ]);
+}
+function examplesLine(examples) {
+    return examples && examples.length ? `Examples: ${examples.join('; ')}` :
+        undefined;
+}
+// Joins the non-empty parts into one description, separated by blank lines so
+// each reads as its own paragraph in the emitted metadata.
+function composeText(parts) {
+    const kept = parts.map(p => (p === undefined ? undefined : p.trim()))
+        .filter((p) => !!p);
+    return kept.length ? kept.join('\n\n') : undefined;
+}
+// Renders the trailing `OPTIONS(...)` clause for a graph element -- a folded
+// `description` string and/or a structured `synonyms` array -- or undefined
+// when there is nothing to emit. Both map to BigQuery's
+// PropertyGraph{Label,Property}Options (`description` singular, `synonyms`
+// repeated), honored on element-table labels (DEFAULT LABEL, before PROPERTIES)
+// and on derived properties and measures (after the alias). Statement-level
+// graph OPTIONS is intentionally not emitted: it parses but BigQuery silently
+// drops it (verified live; create_property_graph_options is off for BigQuery).
+function optionsClause(description, synonyms) {
+    const parts = [];
+    if (description)
+        parts.push(`description=${quote(description)}`);
+    if (synonyms && synonyms.length) {
+        parts.push(`synonyms=[${synonyms.map(quote).join(', ')}]`);
+    }
+    return parts.length ? `OPTIONS(${parts.join(', ')})` : undefined;
+}
+// Renders a value as a BigQuery double-quoted string literal. Backslash and the
+// quote are escaped, and control characters that cannot appear raw inside a
+// quoted literal (newline, carriage return, tab) are escaped too, so a
+// multi-line description does not produce a broken literal.
+function quote(s) {
+    const escaped = s.replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+    return `"${escaped}"`;
+}

package/build/ts/kcmd/semantic/binding.d.ts

@@ -0,0 +1,3 @@
+export type QuoteFn = (identifier: string) => string;
+export declare function boundTable(dataSource: string, warnings: string[], context: string, quote: QuoteFn): string;
+export declare function spannerTable(dataSource: string, warnings: string[], context: string): string;

package/build/ts/kcmd/semantic/binding.js

@@ -0,0 +1,92 @@
+"use strict";
+// Which physical table an entity is bound to.
+//
+// A binding profile gives an entity a `source`, and every caller that touches
+// real rows has to turn that string into a table name: the DDL generator
+// naming an input table, the runtime building a statement, the agent tool
+// derivation describing what a lookup reads. They must agree, so the rule
+// lives in one place rather than in each of them.
+//
+// This is a binding concern, not a Spanner one. It sits outside the deploy
+// path deliberately -- `runtime/` reads it, and a runtime that had to import a
+// DDL generator to learn a table name would be describing a layering that is
+// not real.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.boundTable = boundTable;
+exports.spannerTable = spannerTable;
+const loader_1 = require("./loader");
+const sql_identifiers_1 = require("./sql_identifiers");
+// The table `dataSource` names within its own database: its final dotted or
+// path segment, except that a Spanner table keeps its schema (`ops.stations`),
+// each part quoted. A query, which holds whitespace, is returned in
+// parentheses with a warning.
+function boundTable(dataSource, warnings, context, quote) {
+    const trimmed = (dataSource ?? '').trim();
+    if (!trimmed) {
+        warnings.push(`${context}: empty data source; the table reference will be invalid`);
+        return quote('');
+    }
+    if (/\s/.test(trimmed)) {
+        warnings.push(`${context}: data source '${trimmed}' looks like a query, not a table reference; ` +
+            `emitting it verbatim (a graph element table requires a table)`);
+        return `(${trimmed})`;
+    }
+    // Reduce a URI to its final path segment. A Spanner source keeps every
+    // dotted part of it, and any other source keeps the last.
+    const source = isResourceUri(trimmed) ? finalPathSegment(trimmed) : trimmed;
+    const parts = splitDotted(source).map(unquote);
+    const kept = (0, loader_1.sourceTableOf)(trimmed)?.system === 'spanner' ? parts : parts.slice(-1);
+    return kept.map(quote).join('.');
+}
+// `boundTable` in GoogleSQL, which is what the Spanner DDL generator wants and
+// what every caller wanted when there was one backend.
+function spannerTable(dataSource, warnings, context) {
+    return boundTable(dataSource, warnings, context, sql_identifiers_1.quoteIdentifier);
+}
+// A resource URI (`//host/...`) or any `scheme://...` URI, as opposed to a bare
+// or dotted table reference. The loader gives the IR a BigQuery or BigLake
+// table as its dotted name, a Spanner, AlloyDB or Cloud SQL table as its
+// resource URI, with the leading `//`, and a third-party table as its entry
+// name (see `parseSource` and `sourceToDataSource`). It rejects any `scheme://`
+// source, so only a hand-built IR reaches that arm.
+function isResourceUri(source) {
+    return source.startsWith('//') || /^[a-z][\w+.-]*:\/\//i.test(source);
+}
+// The final non-empty path segment of a URI (`.../tables/Customer` →
+// `Customer`).
+function finalPathSegment(uri) {
+    const segments = uri.split('/').filter(s => s.length > 0);
+    return segments.pop() ?? uri;
+}
+// Splits a dotted source into its segments, treating a backtick- or
+// double-quote-delimited segment as opaque so a dot INSIDE quotes does not
+// split an identifier: `proj.ds.`weird.name`` yields ['proj', 'ds',
+// '`weird.name`'], not a spurious break inside the quoted table name.
+function splitDotted(source) {
+    const parts = [];
+    let cur = '';
+    let quote = null;
+    for (const ch of source) {
+        if (quote) {
+            cur += ch;
+            if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '`' || ch === '"') {
+            quote = ch;
+            cur += ch;
+        }
+        else if (ch === '.') {
+            parts.push(cur);
+            cur = '';
+        }
+        else {
+            cur += ch;
+        }
+    }
+    parts.push(cur);
+    return parts;
+}
+function unquote(part) {
+    return part.replace(/^[`"]/, '').replace(/[`"]$/, '');
+}

package/build/ts/kcmd/semantic/catalog_entry.d.ts

@@ -0,0 +1,24 @@
+import type { ApiResult } from '../gcp/api';
+export interface EntryLookup {
+    lookupEntry(project: string, location: string, name: string): Promise<ApiResult<{
+        entryType?: string;
+        fullyQualifiedName?: string;
+        entrySource?: {
+            system?: string;
+        };
+    }>>;
+}
+export type Read<T> = {
+    result: T;
+} | {
+    unreadable: true;
+    status: 403 | 404;
+    message?: string;
+} | {
+    error: string;
+    status?: number;
+};
+export declare function read<T>(what: string, call: () => Promise<ApiResult<T>>): Promise<Read<T>>;
+export declare function lookupSystemEntry(catalog: EntryLookup, system: string, project: string, location: string, resourceName: string): Promise<Read<{
+    entryType?: string;
+}>>;

package/build/ts/kcmd/semantic/catalog_entry.js

@@ -0,0 +1,35 @@
+"use strict";
+// Reading a table's Knowledge Catalog entry, which the dialect lookup and the
+// source check share, so both read an entry, and the answer, the same way.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.read = read;
+exports.lookupSystemEntry = lookupSystemEntry;
+const dataplex_1 = require("../gcp/dataplex");
+// Makes the call `call`, which `what` names in a message. Never throws.
+async function read(what, call) {
+    let res;
+    try {
+        res = await call();
+    }
+    catch (err) {
+        return { error: `${what} failed: ${err?.message ?? err}` };
+    }
+    // Dataplex answers 403 both when an entry does not exist and when the caller
+    // may not read it; the admin APIs answer 404 for a missing resource.
+    if (res.status === 403 || res.status === 404) {
+        return { unreadable: true, status: res.status, message: res.message };
+    }
+    if (res.status !== 200 || !res.result) {
+        return {
+            error: `${what} failed (HTTP ${res.status}${res.message ? `: ${res.message}` : ''}).`,
+            ...(res.status !== 200 && { status: res.status }),
+        };
+    }
+    return { result: res.result };
+}
+// Looks up the catalog entry of the table whose resource name is
+// `resourceName`, in the entry group `@<system>` at `location`.
+function lookupSystemEntry(catalog, system, project, location, resourceName) {
+    const name = `${(0, dataplex_1.catalogContainer)(project, location, `@${system}`)}/entries/${resourceName}`;
+    return read('looking up its Knowledge Catalog entry', () => catalog.lookupEntry(project, location, name));
+}

package/build/ts/kcmd/semantic/converters/owl/convert.d.ts

@@ -0,0 +1,26 @@
+export interface ConvertResult {
+    yaml: string;
+    stats: {
+        classes: number;
+        datatypeProperties: number;
+        objectProperties: number;
+    };
+    warnings: string[];
+}
+/**
+ * Converts a Turtle (.ttl) OWL ontology to an OSI YAML document.
+ *
+ * `modelName` names the resulting semantic model (the CLI derives it from the
+ * source filename). The output is a purely LOGICAL model -- see to_ir.ts and
+ * the user guide -- with no physical binding; it loads and pushes to Knowledge
+ * Catalog as-is, and a graph deploy adds bindings on top.
+ *
+ * `opts.compactFlow` emits the compact flow YAML layout (the `owl import
+ * --compact` flag) instead of the default block layout; both parse identically.
+ *
+ * Throws only on malformed Turtle (the parser's error); mapping gaps are
+ * reported as warnings, not failures.
+ */
+export declare function convertOwlToOsi(turtle: string, modelName: string, opts?: {
+    compactFlow?: boolean;
+}): ConvertResult;