@google-cloud/kcmd 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,18 @@
+import { ActionParameter } from './ir';
+export declare function isParameterRequired(param: ActionParameter): boolean;
+export declare function storeCodeFor(dataType: string): string;
+export declare function sentence(text: string): string;
+/**
+ * One value, parsed to the store type its declared ontology type implies.
+ *
+ * Exported because a read has the same problem a write does: a filter on a
+ * typed column has to be bound AS that type, or the predicate needs a cast and
+ * no index can answer it. Sharing this also means one answer to what counts as
+ * an Integer or a Date, rather than one for writes and another for reads.
+ */
+export declare function bindScalar(param: ActionParameter, raw: unknown): {
+    value: unknown;
+    code: string;
+} | {
+    error: string;
+};

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

@@ -0,0 +1,152 @@
+"use strict";
+// Leaf helpers for action parameter optionality, scalar type checking, and
+// store type codes -- shared by deploy-time validation and run-time execution
+// without pulling store clients into the validation layer.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isParameterRequired = isParameterRequired;
+exports.storeCodeFor = storeCodeFor;
+exports.sentence = sentence;
+exports.bindScalar = bindScalar;
+function isParameterRequired(param) {
+    if (param.required !== undefined)
+        return param.required;
+    return param.default === undefined;
+}
+function storeCodeFor(dataType) {
+    switch (dataType) {
+        case 'Integer':
+            return 'INT64';
+        case 'Float':
+            return 'FLOAT64';
+        case 'Decimal':
+            return 'NUMERIC';
+        case 'Boolean':
+            return 'BOOL';
+        case 'Date':
+            return 'DATE';
+        case 'DateTime':
+        case 'DateTimeTz':
+            return 'TIMESTAMP';
+        default:
+            return 'STRING';
+    }
+}
+// Ends a fragment that is about to be followed by another sentence.
+function sentence(text) {
+    const trimmed = text.trim();
+    return /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
+}
+// What Spanner accepts for a DATE and a TIMESTAMP parameter. The zone is
+// required rather than defaulted, because a timestamp written without one
+// means a different instant to every reader who supplies the missing part.
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const RFC3339_TIMESTAMP = /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[-+]\d{2}:?\d{2})$/;
+// Whether `text` is a day that exists, written the one way Spanner reads.
+// `Date.parse` answers neither question: it accepts '03/04/2026', and it reads
+// '2026-02-30' as the second of March rather than rejecting it. A round trip
+// answers both, because a day that rolled over comes back written differently.
+function isCalendarDay(text) {
+    if (!ISO_DATE.test(text))
+        return false;
+    const utc = new Date(`${text}T00:00:00Z`);
+    return !Number.isNaN(utc.getTime()) && utc.toISOString().startsWith(text);
+}
+/**
+ * One value, parsed to the store type its declared ontology type implies.
+ *
+ * Exported because a read has the same problem a write does: a filter on a
+ * typed column has to be bound AS that type, or the predicate needs a cast and
+ * no index can answer it. Sharing this also means one answer to what counts as
+ * an Integer or a Date, rather than one for writes and another for reads.
+ */
+function bindScalar(param, raw) {
+    // A parameter whose type resolved to nothing. The loader warns and validate
+    // refuses to push such a model, so this is reached only through the library
+    // entry point -- and there is no type to parse the value against, so there
+    // is nothing to bind.
+    const type = param.type;
+    if (type === undefined) {
+        return {
+            error: `Action parameter '${param.name}' has no type: it states no ` +
+                `scalar 'type' and projects no field that supplies one, so a value ` +
+                `cannot be bound to it.`,
+        };
+    }
+    // Everything below stringifies the value before matching it against the
+    // type, which is what lets a JSON `"12347"` bind as an Integer. An object or
+    // an array has a string form too -- `[object Object]` -- and it would sail
+    // through as a String and be written to the store verbatim. A parameter
+    // carries ONE scalar, so a composite is refused here rather than flattened.
+    if (raw !== undefined && raw !== null && typeof raw === 'object') {
+        return {
+            error: `Action parameter '${param.name}' (${type}) was given ${Array.isArray(raw) ? 'a list' :
+                'an object'}, but a parameter ` +
+                `carries a single scalar value.`,
+        };
+    }
+    // An empty String IS a value: `--arg memo=` is the caller saying the memo is
+    // blank, which is a different statement from not passing one. For every
+    // other type there is no value empty text could be, so it stays an error.
+    if (raw === undefined || raw === null ||
+        (`${raw}`.trim() === '' && type !== 'String')) {
+        return {
+            error: `Action parameter '${param.name}' (${type}) was not given ` +
+                `a value.`,
+        };
+    }
+    const text = `${raw}`.trim();
+    const code = storeCodeFor(type);
+    switch (type) {
+        case 'Integer':
+            if (!/^[-+]?\d+$/.test(text)) {
+                return { error: `'${param.name}' is an Integer, but '${text}' is not.` };
+            }
+            // INT64 travels as a string over the REST surface; a JSON number would
+            // lose precision above 2^53.
+            return { value: text, code };
+        case 'Float':
+            if (!Number.isFinite(Number(text))) {
+                return { error: `'${param.name}' is a Float, but '${text}' is not.` };
+            }
+            return { value: Number(text), code };
+        case 'Decimal':
+            if (!/^[-+]?\d+(\.\d+)?$/.test(text)) {
+                return { error: `'${param.name}' is a Decimal, but '${text}' is not.` };
+            }
+            // NUMERIC travels as a string, for the same reason: an exact decimal
+            // routed through a JSON number stops being exact.
+            return { value: text, code };
+        case 'Boolean':
+            if (!/^(true|false)$/i.test(text)) {
+                return { error: `'${param.name}' is a Boolean, but '${text}' is not.` };
+            }
+            return { value: /^true$/i.test(text), code };
+        case 'Date':
+            // Spanner reads a DATE as YYYY-MM-DD and nothing else. '03/04/2026' is
+            // the fourth of March to one reader and the third of April to another,
+            // so the shape is checked -- and then the calendar, because a shape is
+            // not a day.
+            if (!isCalendarDay(text)) {
+                return {
+                    error: `'${param.name}' is a Date, but '${text}' is not one. Dates are written YYYY-MM-DD.`,
+                };
+            }
+            return { value: text, code };
+        case 'DateTime':
+        case 'DateTimeTz':
+            if (!RFC3339_TIMESTAMP.test(text) || !isCalendarDay(text.slice(0, 10))) {
+                return {
+                    error: `'${param.name}' is a ${type}, but '${text}' is not a timestamp. Timestamps are written like ` +
+                        `2026-03-04T10:00:00Z, with the zone.`,
+                };
+            }
+            return { value: text, code };
+        default:
+            // `raw`, not `text`. The trim above exists to parse a number or a date
+            // off a command line; a String parameter is not parsed, it IS the value.
+            // Trimming here would store `see ticket` for `--arg memo=" see ticket "`
+            // -- the caller's text altered on the way to the store, by a rule
+            // nothing states.
+            return { value: `${raw}`, code };
+    }
+}

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

@@ -0,0 +1,14 @@
+import { CatalogClient } from '../gcp/dataplex';
+import { ReadResult } from './kc_converter';
+import { FileCopy } from './kc_custom_types';
+export interface KcPullOptions {
+    project: string;
+    location: string;
+    entryGroup: string;
+    v2Aspects?: boolean;
+    systemTypeProject?: string;
+}
+export interface KcPullResult extends ReadResult {
+    rawFiles?: FileCopy[];
+}
+export declare function pullKnowledgeCatalog(cat: CatalogClient, opts: KcPullOptions): Promise<KcPullResult>;

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

@@ -0,0 +1,346 @@
+"use strict";
+// Pull: fetch a semantic model from a live Knowledge Catalog into the IR.
+//
+// The read-direction counterpart of `deployKnowledgeCatalog` (push, in
+// `deploy_knowledge_catalog.ts`). Unlike a write, a pull needs no server-side
+// type provisioning -- only that the `semantic-*` entries exist. It enumerates
+// the entry group, keeps the semantic entries, hydrates each one's aspect data
+// (a BASIC list omits aspect data, so each entry is re-fetched with its aspect
+// types -- an entity needs BOTH its `semantic-entity` aspect and the built-in
+// `schema` aspect), and hands the hydrated entries to the pure reader
+// (`kc_converter.modelsFromCatalogResources`). With the first-generation
+// aspects it also returns the file copies a push stored of the model and
+// profile files, for the caller to write instead of the rebuilt model.
+//
+// TODO(#278): Layer 2 push/pull symmetry. This is the pull half over the
+// pure `kc_converter` codec; the push half (`deployKnowledgeCatalog`) still
+// lives in `deploy_knowledge_catalog.ts`. Once #278 merges, rename that
+// file to `push_kc.ts` (repointing `src/tool/commands.ts` and its test) so
+// the orchestration layer reads as `push_kc` / `pull_kc`. Rename only -- no
+// logic moves.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pullKnowledgeCatalog = pullKnowledgeCatalog;
+const dataplex_1 = require("../gcp/dataplex");
+const kc_actions_1 = require("./kc_actions");
+const kc_constraints_1 = require("./kc_constraints");
+const kc_converter_1 = require("./kc_converter");
+const kc_custom_types_1 = require("./kc_custom_types");
+const kc_ids_1 = require("./kc_ids");
+const sql_parser_1 = require("./sql_parser");
+// Upper bound on in-flight aspect-hydration fetches during a pull.
+const HYDRATE_CONCURRENCY = 8;
+// Reads the semantic model back from a Knowledge Catalog entry group. Emits no
+// console output; soft warnings (from the reader) are returned for the caller
+// to print. Hard failures -- more than one model in the group, a fetch error
+// on any entry or its links, or file copies that are not one finished push's
+// -- throw, so the pull aborts rather than write a partial model.
+async function pullKnowledgeCatalog(cat, opts) {
+    await (0, sql_parser_1.loadSqlEngine)();
+    const destination = `${opts.project}.${opts.location}.${opts.entryGroup}`;
+    const warnings = [];
+    // Enumerate the group (paging is inherently sequential) and pick the semantic
+    // entries, then hydrate their aspects concurrently: a BASIC list omits aspect
+    // data, so each entry needs its own lookupEntry, and those fetches are
+    // independent. The pool preserves input order so warnings stay deterministic.
+    const targets = [];
+    for await (const entry of cat.listEntries(opts.project, opts.location, opts.entryGroup)) {
+        // With v2Aspects on, a pull returns no file copies, so it fetches none.
+        if (opts.v2Aspects && isFileCopyEntry(entry))
+            continue;
+        const aspectTypes = semanticAspectTypes(entry.entryType, opts.v2Aspects);
+        if (aspectTypes)
+            targets.push({ entry, aspectTypes });
+        // else: not part of a semantic model; ignore it.
+    }
+    // An entry group holds exactly one semantic model. Zero anchors is a clean
+    // "nothing to pull" (the reader returns no models); more than one is an
+    // unexpected catalog state we refuse to guess through -- name the anchors and
+    // fail so it can be fixed at the source.
+    const anchors = targets.filter(t => t.entry.entryType?.endsWith('/entryTypes/semantic-model'));
+    if (anchors.length > 1) {
+        const ids = anchors.map(a => (0, kc_ids_1.entryIdOf)(a.entry.name)).sort();
+        throw new Error(`entry group ${destination} holds ${anchors.length} semantic models (${ids.join(', ')}); expected exactly one. Remove the extra anchor(s) ` +
+            `from the catalog and pull again.`);
+    }
+    // Hydrate every semantic entry. A failed fetch means part of the model would
+    // be silently missing, so abort rather than reconstruct an incomplete model.
+    const hydrated = await mapConcurrent(targets, HYDRATE_CONCURRENCY, async ({ entry, aspectTypes }) => opts.v2Aspects ?
+        fetchEveryAspect(cat, opts, entry, aspectTypes) :
+        fetchEntry(cat, opts, entry, aspectTypes));
+    // Second fetch pass: with the first-generation types, the schema-join links
+    // of the relationships, which listing entries does not return. Links are
+    // listed per entity entry and deduplicated, since each comes back from both
+    // endpoints, and a failed lookup aborts the pull. With v2Aspects on, pull
+    // reads no link.
+    const entityEntries = opts.v2Aspects ? [] : hydrated.filter(e => e.entryType?.endsWith('/entryTypes/semantic-entity'));
+    const linkLists = await mapConcurrent(entityEntries, HYDRATE_CONCURRENCY, async (entry) => {
+        const res = await cat.lookupEntryLinks(opts.project, opts.location, {
+            entry: entry.name,
+            entryLinkTypes: [new kc_ids_1.Namer(opts).typeName('entryLink', 'schema-join')],
+        });
+        if (res.status !== 200 || !res.result) {
+            throw new Error(`failed to fetch entry links for '${entry.name}' ` +
+                `(status ${res.status}); pull aborted`);
+        }
+        return res.result;
+    });
+    const seenLinks = new Set();
+    const entryLinks = [];
+    for (const links of linkLists) {
+        for (const link of links) {
+            const key = (0, kc_converter_1.linkDedupKey)(link);
+            if (seenLinks.has(key))
+                continue;
+            seenLinks.add(key);
+            entryLinks.push(link);
+        }
+    }
+    const read = (0, kc_converter_1.modelsFromCatalogResources)(hydrated, entryLinks, { v2Aspects: opts.v2Aspects });
+    if (opts.v2Aspects) {
+        warnings.push(...read.warnings);
+        return { ...read, warnings: [...new Set(warnings)] };
+    }
+    // A copy belongs to the group's one model, so with no model there are none.
+    if (!read.models.length) {
+        warnings.push(...read.warnings);
+        return { models: [], rawFiles: [], warnings: [...new Set(warnings)] };
+    }
+    // The first-generation aspects cannot hold the whole model, so the caller
+    // writes these copies instead of the model rebuilt from the aspects. That
+    // needs the copy of the model file, `<model>.yaml`, which is where pull
+    // writes the model. Without it the rebuilt model is written, as for a model
+    // pushed before copies were stored.
+    const model = read.models[0].name;
+    // The model's own copies sit under its anchor's `.files.` prefix. A copy
+    // another model left behind is not one of them.
+    const own = `${(0, kc_ids_1.entryIdOf)(anchors[0].entry.name)}.files.`;
+    const before = warnings.length;
+    const copies = readFileCopies(hydrated.filter(e => (0, kc_ids_1.entryIdOf)(e.name).startsWith(own)), warnings);
+    const skipped = warnings.slice(before);
+    // Every copy one push stores carries that push's id and how many copies it
+    // stored. Copies whose ids differ, or of which only some carry one, or a
+    // number of copies other than that count, mean the last push stopped
+    // partway. Writing them would mix files from two pushes or leave one out.
+    // A push that stores copies also labels the model entry with its push id,
+    // and writes that entry first. A labeled model whose copies are missing or
+    // carry another id means the last push stopped before storing them.
+    // Writing the copies of an earlier push, or rebuilding, would overwrite
+    // the local files. The hydrated entries keep the order of `targets`.
+    const count = copies[0]?.pushFileCount;
+    const anchor = hydrated[targets.indexOf(anchors[0])];
+    const label = anchor.entrySource?.labels?.[kc_custom_types_1.PUSH_ID_LABEL];
+    const unfinished = new Set(copies.map(f => f.pushId)).size > 1 ?
+        'its file copies in the catalog come from different pushes' :
+        count !== undefined && copies.length < count ?
+            `the catalog holds ${copies.length} of its ${count} file copies` :
+            count !== undefined && copies.length > count ?
+                `the catalog holds ${copies.length} file copies, but the push stored ` +
+                    `${count}` :
+                label !== undefined && !copies.length ?
+                    (skipped.length ? 'the catalog holds no readable file copy' :
+                        'the catalog holds none of its file copies') :
+                    label !== undefined && copies[0].pushId !== label ?
+                        'its model entry and its file copies come from different pushes' :
+                        undefined;
+    if (unfinished) {
+        // A skipped copy is often why the count is off, so its warning goes with
+        // the error.
+        throw new Error(`the last push of model '${model}' did not finish: ${unfinished}, ` +
+            `so pull writes nothing. Push again, then pull.` +
+            skipped.map(w => ` ${w}.`).join(''));
+    }
+    if (copies.some(f => f.fileName === `${model}.yaml`)) {
+        // The rebuilt model is not written, so its warnings are left out.
+        return {
+            models: read.models,
+            rawFiles: copies,
+            warnings: [...new Set(warnings)],
+        };
+    }
+    warnings.push(...read.warnings);
+    warnings.push(copies.length ?
+        `the stored copies of model '${model}' hold no '${model}.yaml', so ` +
+            `the model file is rebuilt from the catalog's aspects and may ` +
+            `differ from what was pushed` :
+        'no stored copy of the model file was found, so it is rebuilt from ' +
+            'the catalog\'s aspects and may differ from what was pushed; ' +
+            'push it again to store a copy');
+    return { models: read.models, rawFiles: [], warnings: [...new Set(warnings)] };
+}
+// Fetches `entry` with the aspects of `aspectTypes`, at `paths` when given.
+// Throws on a failed fetch.
+async function fetchEntry(cat, opts, entry, aspectTypes, paths) {
+    const res = await cat.lookupEntry(opts.project, opts.location, entry.name, { aspects: aspectTypes, paths });
+    if (res.status !== 200 || !res.result) {
+        throw new Error(`failed to fetch entry '${entry.name}' (status ${res.status}); pull aborted`);
+    }
+    return res.result;
+}
+// Most aspects Dataplex returns for one entry in one read.
+const MAX_ASPECTS_PER_READ = 100;
+// Most bytes of path and query Dataplex accepts in a GET.
+const MAX_URL_BYTES = 16_384;
+// Fetches `entry` with every aspect of `aspectTypes`, one read at a time. A
+// read that returns MAX_ASPECTS_PER_READ is repeated once per type, and a type
+// that returns that many is read again at the entry and at each field.
+async function fetchEveryAspect(cat, opts, entry, aspectTypes) {
+    const full = (e) => Object.keys(e.aspects ?? {}).length >= MAX_ASPECTS_PER_READ;
+    const read = await fetchEntry(cat, opts, entry, aspectTypes);
+    if (!full(read))
+        return read;
+    const byType = [];
+    for (const t of aspectTypes) {
+        byType.push(await fetchEntry(cat, opts, entry, [t]));
+    }
+    const schema = byType[aspectTypes.findIndex(t => t.endsWith('/aspectTypes/schema'))];
+    const paths = [
+        '',
+        ...Object.values(schema?.aspects ?? {})
+            .flatMap(a => a.data?.fields ?? [])
+            .map(f => `Schema.${f.name}`)
+    ];
+    const byPath = [];
+    for (const t of aspectTypes.filter((_, i) => full(byType[i]))) {
+        for (const batch of pathBatches(opts, entry, t, paths)) {
+            byPath.push(await fetchEntry(cat, opts, entry, [t], batch));
+        }
+    }
+    const reads = [...byType, ...byPath];
+    return { ...read, aspects: Object.assign({}, ...reads.map(r => r.aspects)) };
+}
+// Splits `paths` into batches for reads of `type` on `entry`, each within
+// MAX_URL_BYTES. A batch holds fewer than MAX_ASPECTS_PER_READ paths, and a
+// path holds at most one instance of a type, so no read comes back cut.
+function pathBatches(opts, entry, type, paths) {
+    // Bytes of `params` in the URL, with the '?' or '&' before them.
+    const bytes = (params) => new URLSearchParams(params).toString().length + 1;
+    const base = `/v1/${(0, dataplex_1.catalogContainer)(opts.project, opts.location)}:lookupEntry`
+        .length +
+        bytes([['entry', entry.name], ['view', 'CUSTOM'], ['aspectTypes', type]]);
+    const batches = [];
+    let batch = [];
+    let size = base;
+    for (const path of paths) {
+        const add = bytes([['paths', path]]);
+        if (batch.length === MAX_ASPECTS_PER_READ - 1 ||
+            size + add > MAX_URL_BYTES) {
+            batches.push(batch);
+            batch = [];
+            size = base;
+        }
+        batch.push(path);
+        size += add;
+    }
+    return [...batches, batch];
+}
+// True when an entry is a file copy, matched by its entry type's id suffix so
+// the project the custom type lives in need not be known.
+function isFileCopyEntry(entry) {
+    return entry.entryType?.endsWith(`/entryTypes/${kc_custom_types_1.FILE_COPY_TYPE_ID}`) ?? false;
+}
+// The file copies among the hydrated entries, sorted by file name, each with
+// the push id and copy count it carries. A copy whose aspect holds no file
+// name or no content is skipped with a warning.
+function readFileCopies(entries, warnings) {
+    const files = [];
+    for (const entry of entries) {
+        if (!isFileCopyEntry(entry))
+            continue;
+        const aspect = Object.entries(entry.aspects ?? {}).find(([key, a]) => key.endsWith(`.${kc_custom_types_1.FILE_COPY_TYPE_ID}`) ||
+            (a.aspectType ?? '').endsWith(`/aspectTypes/${kc_custom_types_1.FILE_COPY_TYPE_ID}`));
+        const data = aspect?.[1].data;
+        if (typeof data?.fileName !== 'string' || data.fileName === '' ||
+            typeof data.content !== 'string') {
+            warnings.push(`file copy '${(0, kc_ids_1.entryIdOf)(entry.name)}' holds no file name or no ` +
+                `content; it is skipped`);
+            continue;
+        }
+        files.push({
+            fileName: data.fileName,
+            content: data.content,
+            ...(typeof data.pushId === 'string' ? { pushId: data.pushId } : {}),
+            ...(typeof data.pushFileCount === 'number' ?
+                { pushFileCount: data.pushFileCount } :
+                {}),
+        });
+    }
+    return files.sort((a, b) => a.fileName < b.fileName ? -1 : a.fileName > b.fileName ? 1 : 0);
+}
+// The aspect types each second-generation entry type is read with.
+const OBJECT_ASPECTS = ['guidelines', 'semantic-extensions', 'overview'];
+const V2_ASPECT_TYPES = new Map([
+    ['semantic-model', ['semantic-model', ...OBJECT_ASPECTS]],
+    [
+        'semantic-entity',
+        ['semantic-entity', 'schema', 'sql-expressions', ...OBJECT_ASPECTS]
+    ],
+    [
+        'semantic-metric', ['semantic-metric', 'sql-expressions', ...OBJECT_ASPECTS]
+    ],
+    ['semantic-relationship', ['semantic-relationship', ...OBJECT_ASPECTS]],
+]);
+// The aspect types to read for a semantic entry, in its entry type's project
+// and location: V2_ASPECT_TYPES with `v2Aspects` on, the first-generation set
+// otherwise. Undefined for an entry outside a semantic model.
+function semanticAspectTypes(entryType, v2Aspects) {
+    const marker = '/entryTypes/';
+    const idx = entryType?.indexOf(marker) ?? -1;
+    if (idx < 0)
+        return undefined;
+    const typeBase = entryType.slice(0, idx);
+    const t = entryType.slice(idx + marker.length);
+    const aspectType = (name) => `${typeBase}/aspectTypes/${name}`;
+    const v2Types = v2Aspects ? V2_ASPECT_TYPES.get(t) : undefined;
+    if (v2Types)
+        return v2Types.map(aspectType);
+    switch (t) {
+        case 'semantic-model':
+            return [aspectType('semantic-model'), aspectType('guidelines')];
+        case 'semantic-entity':
+            return [
+                aspectType('semantic-entity'), aspectType('schema'),
+                aspectType('guidelines')
+            ];
+        case 'semantic-metric':
+            return [aspectType('semantic-metric'), aspectType('guidelines')];
+        case kc_custom_types_1.ACTION_TYPE_ID:
+            // An action's entry type is custom (see kc_custom_types.ts), so it
+            // lives in the destination project rather than under `dataplex-types`;
+            // `typeBase` already points there, and kc_actions.ts names the aspects
+            // to fetch beneath it.
+            return (0, kc_actions_1.actionAspectTypes)(typeBase);
+        case kc_custom_types_1.CONSTRAINT_TYPE_ID:
+            // Custom for the same reason, and named through the same `typeBase`.
+            return (0, kc_constraints_1.constraintAspectTypes)(typeBase);
+        case kc_custom_types_1.FILE_COPY_TYPE_ID:
+            // Custom too: one aspect holding the file's name and text.
+            return [aspectType(kc_custom_types_1.FILE_COPY_TYPE_ID)];
+        default:
+            return undefined;
+    }
+}
+// Maps `items` through `fn` with at most `limit` calls in flight, returning
+// results in input order (so downstream ordering stays deterministic).
+async function mapConcurrent(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    let failed = false;
+    async function worker() {
+        // Stop claiming new items once any worker has thrown: Promise.all rejects on
+        // the first failure, so fanning out more fetches is wasted work whose own
+        // rejections would surface as unhandled-rejection noise.
+        while (next < items.length && !failed) {
+            const i = next++;
+            try {
+                results[i] = await fn(items[i]);
+            }
+            catch (err) {
+                failed = true;
+                throw err;
+            }
+        }
+    }
+    const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+    await Promise.all(workers);
+    return results;
+}

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

@@ -0,0 +1,54 @@
+import { Field, SemanticModel } from './ir';
+/**
+ * Why inheritance cannot be resolved. `unknown-parent` can be a pruning
+ * artefact, since a profile can drop a supertype whole; a cycle or an
+ * ambiguously inherited field cannot, because pruning only removes things.
+ */
+export declare class InheritanceError extends Error {
+    readonly kind: 'unknown-parent' | 'cycle' | 'ambiguous-field';
+    constructor(kind: 'unknown-parent' | 'cycle' | 'ambiguous-field', message: string);
+}
+export interface ResolveResult {
+    model: SemanticModel;
+    warnings: string[];
+}
+/**
+ * What a `concept` name may refer to, and the fields it declares.
+ *
+ * One lookup serves every construct that names a concept -- an action's
+ * `affects`, and a derived action parameter's `concept`/`field` pair -- so the
+ * two can never disagree about what `Order` is or which fields it has.
+ *
+ * Entities are indexed FIRST, so a name that is both an entity and a
+ * relationship resolves to the entity. `kind` exists to say `entity 'X'` or
+ * `relationship 'X'` in a message, and to pick which fields count.
+ *
+ * Only a many-to-many relationship has fields of its own: they live on the
+ * junction table backing it (see Association), and an enrollment's grade is as
+ * ordinary a field as an order's total. A plain foreign-key edge declares none.
+ *
+ * Inheritance is resolved, because a subtype's own `fields` omit everything it
+ * inherits. Resolution THROWS on an `extends` naming an entity the model does
+ * not declare, on a cycle, and on a field inherited ambiguously; a caller that
+ * cannot report that -- the loader, which is lenient by design -- catches it
+ * and works from the unresolved model instead.
+ */
+export interface DeclaredConcept {
+    kind: 'entity' | 'relationship';
+    fields: Map<string, Field>;
+}
+export declare function declaredConceptFields(model: SemanticModel): Map<string, DeclaredConcept>;
+/**
+ * Returns a clone of `model` with every entity's `extends` expanded to its full
+ * transitive ancestor set and its `fields` flattened to include inherited
+ * fields, less any a profile excludes on that entity. The input is never
+ * mutated. An entity with no `extends` keeps its own fields, so a model with no
+ * inheritance and no exclusions resolves to an equivalent model.
+ * `targetDialect` is the SQL that an inherited field's target text and its
+ * ANSI_SQL entries are read in to find their comments. It is BigQuery unless
+ * given, as the graph generators read the target text.
+ *
+ * Reading an inherited field's SQL needs the SQL parser, so call
+ * `loadSqlEngine()` first. Without it, this throws the parser's plain Error.
+ */
+export declare function resolveInheritance(model: SemanticModel, targetDialect?: string): ResolveResult;