@google-cloud/kcmd 0.0.0-stage → 0.2.0

package/build/ts/kcmd/layouts/standard.js

@@ -0,0 +1,108 @@
+"use strict";
+// Implements the standard layout (yaml files in directory)
+//
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StandardLayout = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const glob = __importStar(require("glob"));
+const yaml = __importStar(require("yaml"));
+class StandardLayout {
+    _catalogPath;
+    _index = new Map();
+    constructor(catalogPath) {
+        this._catalogPath = catalogPath;
+    }
+    async init() {
+        this._index.clear();
+        if (!fs.existsSync(this._catalogPath)) {
+            return;
+        }
+        const matches = await glob.glob('**/*.yaml', {
+            cwd: this._catalogPath,
+            absolute: true,
+            nodir: true,
+        });
+        for (const localPath of matches) {
+            try {
+                const content = await fs.promises.readFile(localPath, 'utf8');
+                const metadata = yaml.parse(content);
+                if (metadata && metadata.name) {
+                    this._index.set(metadata.name, localPath);
+                }
+            }
+            catch (err) {
+                // A file that fails to read or parse is left out of the index, so it is
+                // never listed and never pushed. Warn rather than drop it silently:
+                // push otherwise makes the destination match the directory, and a file
+                // vanishing from that set is easy to miss.
+                const reason = err instanceof Error ? err.message : String(err);
+                const relPath = path.relative(this._catalogPath, localPath);
+                console.warn(`Skipping unreadable catalog file '${relPath}': ${reason}`);
+            }
+        }
+    }
+    entryExists(name) {
+        const entryPath = this._index.get(name);
+        return !!entryPath && fs.existsSync(entryPath);
+    }
+    listEntries() {
+        return Array.from(this._index.keys());
+    }
+    async loadEntry(name) {
+        const entryPath = this._index.get(name);
+        if (!entryPath || !fs.existsSync(entryPath)) {
+            throw new Error(`Entry not found: ${name}`);
+        }
+        const content = await fs.promises.readFile(entryPath, 'utf8');
+        return yaml.parse(content);
+    }
+    async saveEntry(name, entry) {
+        const entryPath = path.join(this._catalogPath, `${name}.yaml`);
+        await fs.promises.mkdir(path.dirname(entryPath), { recursive: true });
+        await fs.promises.writeFile(entryPath, yaml.stringify(entry), 'utf8');
+        this._index.set(name, entryPath);
+    }
+    async deleteEntry(name) {
+        const entryPath = this._index.get(name);
+        if (!entryPath || !fs.existsSync(entryPath)) {
+            throw new Error(`Entry not found: ${name}`);
+        }
+        await fs.promises.unlink(entryPath);
+        this._index.delete(name);
+    }
+}
+exports.StandardLayout = StandardLayout;

package/build/ts/kcmd/manifest.d.ts

@@ -0,0 +1,34 @@
+import * as gcp from './gcp';
+import { CatalogSource, Sources } from './source';
+export declare const WORKSPACE_LAYOUTS: readonly ["okf"];
+export type WorkspaceLayout = (typeof WORKSPACE_LAYOUTS)[number];
+export interface SnapshotConfig {
+    entries?: string[];
+    aspects?: string[];
+}
+export interface PublishingConfig {
+    entries?: string[];
+    aspects?: string[];
+}
+export interface Scope {
+    type: string;
+    name: string;
+}
+export declare function layoutOf(manifest: any): WorkspaceLayout | undefined;
+export declare function readWorkspaceLayout(path: string): WorkspaceLayout | undefined;
+export declare function writeWorkspaceLayout(path: string, layout: WorkspaceLayout): void;
+export declare class CatalogManifest {
+    readonly source: CatalogSource;
+    readonly snapshotConfig?: SnapshotConfig;
+    readonly publishingConfig?: PublishingConfig;
+    readonly layout?: WorkspaceLayout;
+    private constructor();
+    private static forNewSource;
+    static forPendingEntryGroup(type: Sources.ENTRYGROUP | Sources.KB, name: string, layout?: WorkspaceLayout): CatalogManifest;
+    static initWithEntryGroup(name: string, ctx: gcp.ApiContext): Promise<CatalogManifest>;
+    static initWithBigQuery(dataset: string, ctx: gcp.ApiContext): Promise<CatalogManifest>;
+    static initWithKnowledgeBase(name: string, ctx: gcp.ApiContext): Promise<CatalogManifest>;
+    static initWithSemanticModel(name: string, ctx: gcp.ApiContext): Promise<CatalogManifest>;
+    static load(path: string, ctx: gcp.ApiContext): Promise<CatalogManifest>;
+    save(path: string): void;
+}

package/build/ts/kcmd/manifest.js

@@ -0,0 +1,262 @@
+"use strict";
+// Implements support for creating and loading catalog manifests.
+//
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CatalogManifest = exports.WORKSPACE_LAYOUTS = void 0;
+exports.layoutOf = layoutOf;
+exports.readWorkspaceLayout = readWorkspaceLayout;
+exports.writeWorkspaceLayout = writeWorkspaceLayout;
+const fs = __importStar(require("node:fs"));
+const yaml = __importStar(require("yaml"));
+const z = __importStar(require("zod"));
+const dataplex = __importStar(require("./gcp/dataplex"));
+const source_1 = require("./source");
+const entrygroup_1 = require("./sources/entrygroup");
+const kb_1 = require("./sources/kb");
+// How a workspace stores its entries on disk, when it is not the layout its
+// scope implies (see CatalogSource.layout). `kcmd init --format <layout>`
+// records it, and `pull` and `push` read it back, so the choice is made once
+// per workspace. Only `okf` exists: the entries as an OKF bundle under
+// `bundle/`. A later layout, such as a split workspace that also keeps a
+// semantic model under `catalog/`, is a new value here.
+exports.WORKSPACE_LAYOUTS = ['okf'];
+// The scope types a workspace layout may be recorded for.
+const LAYOUT_SCOPES = [source_1.Sources.ENTRYGROUP, source_1.Sources.KB];
+const manifestSchema = z.object({
+    scope: z.union([z.string(), z.array(z.string())]),
+    // The workspace layout, when it is not the scope's own (see above).
+    layout: z.string().optional(),
+    snapshot: z.object({
+        entries: z.array(z.string()).optional(),
+        aspects: z.array(z.string()).optional()
+    }).optional(),
+    publishing: z.object({
+        entries: z.array(z.string()).optional(),
+        aspects: z.array(z.string()).optional()
+    }).optional(),
+});
+// The workspace layout a parsed catalog.yaml records, or undefined when it
+// records none. Throws naming the problem when the layout is not one kcmd
+// supports, or when the scope's type does not take a layout.
+function layoutOf(manifest) {
+    const layout = manifest?.layout;
+    if (layout === undefined || layout === null)
+        return undefined;
+    if (!exports.WORKSPACE_LAYOUTS.includes(layout)) {
+        throw new Error(`Manifest error: layout '${layout}' is not supported; the supported ` +
+            `layouts are ${exports.WORKSPACE_LAYOUTS.map(l => `'${l}'`).join(', ')}.`);
+    }
+    const scope = manifest?.scope;
+    const type = typeof scope === 'string' ? scope.split('.')[0] : undefined;
+    if (type === undefined || !LAYOUT_SCOPES.includes(type)) {
+        throw new Error(`Manifest error: layout '${layout}' applies only to ` +
+            `${LAYOUT_SCOPES.map(s => `'${s}'`).join(' and ')} scopes.`);
+    }
+    return layout;
+}
+// The workspace layout the catalog.yaml at `path` records, read without
+// resolving the scope, so that a command can choose its path before any call
+// to Knowledge Catalog (the entry group may not exist yet). Undefined when
+// there is no catalog.yaml or it records no layout.
+function readWorkspaceLayout(path) {
+    if (!fs.existsSync(path))
+        return undefined;
+    return layoutOf(yaml.parse(fs.readFileSync(path, 'utf8')));
+}
+// Records `layout` in the catalog.yaml at `path`, keeping every other key and
+// comment as written.
+function writeWorkspaceLayout(path, layout) {
+    const doc = yaml.parseDocument(fs.readFileSync(path, 'utf8'));
+    doc.set('layout', layout);
+    fs.writeFileSync(path, doc.toString(), 'utf8');
+}
+class OfflineEntryGroupSource extends entrygroup_1.EntryGroupSource {
+    async *entries(_ctx) { }
+}
+class OfflineKnowledgeBaseSource extends kb_1.KnowledgeBaseSource {
+    async *entries(_ctx) { }
+}
+class CatalogManifest {
+    source;
+    snapshotConfig;
+    publishingConfig;
+    // The workspace layout, when it is not the scope's own (see the schema).
+    layout;
+    constructor(source, snapshotConfig, publishingConfig, layout) {
+        this.source = source;
+        this.snapshotConfig = snapshotConfig;
+        this.publishingConfig = publishingConfig;
+        this.layout = layout;
+    }
+    // A manifest for a scope `kcmd init` just named, listing the scope's default
+    // aspects under snapshot.aspects.
+    static forNewSource(source) {
+        const aspects = [...source.defaultAspects];
+        return new CatalogManifest(source, aspects.length ? { aspects } : undefined);
+    }
+    // Constructs a manifest for an EntryGroup or KB that has not been created in
+    // Knowledge Catalog yet (used by `kcmd init --format okf` and `kcmd push --dry-run`).
+    static forPendingEntryGroup(type, name, layout) {
+        const [project, location, entryGroup] = name.split('.');
+        if (!project || !location || !entryGroup || name.split('.').length !== 3) {
+            throw new Error('EntryGroup must be in format <projectId>.<locationId>.<entryGroupId>');
+        }
+        const eg = {
+            name: dataplex.catalogContainer(project, location, entryGroup),
+        };
+        const source = type === source_1.Sources.KB
+            ? new OfflineKnowledgeBaseSource(type, name, eg)
+            : new OfflineEntryGroupSource(type, name, eg);
+        const aspects = [...source.defaultAspects];
+        return new CatalogManifest(source, aspects.length ? { aspects } : undefined, undefined, layout);
+    }
+    static async initWithEntryGroup(name, ctx) {
+        const source = await (0, source_1.createSource)(source_1.Sources.ENTRYGROUP, name, ctx);
+        return CatalogManifest.forNewSource(source);
+    }
+    static async initWithBigQuery(dataset, ctx) {
+        const source = await (0, source_1.createSource)(source_1.Sources.BIGQUERY_DATASET, dataset, ctx);
+        return CatalogManifest.forNewSource(source);
+    }
+    static async initWithKnowledgeBase(name, ctx) {
+        const source = await (0, source_1.createSource)(source_1.Sources.KB, name, ctx);
+        return CatalogManifest.forNewSource(source);
+    }
+    static async initWithSemanticModel(name, ctx) {
+        const source = await (0, source_1.createSource)(source_1.Sources.SEMANTIC_MODEL, name, ctx);
+        return CatalogManifest.forNewSource(source);
+    }
+    static async load(path, ctx) {
+        const content = fs.readFileSync(path, 'utf8');
+        const parsed = yaml.parse(content);
+        const result = manifestSchema.safeParse(parsed);
+        if (!result.success) {
+            throw new Error(`Manifest error: ${result.error.message}`);
+        }
+        const scope = result.data.scope;
+        const layout = layoutOf(result.data);
+        let source;
+        if (Array.isArray(scope)) {
+            if (scope.length === 0) {
+                throw new Error('Manifest error: scope array cannot be empty.');
+            }
+            const datasets = [];
+            for (const s of scope) {
+                const dotIndex = s.indexOf('.');
+                if (dotIndex === -1) {
+                    throw new Error(`Manifest error: scope '${s}' is invalid.`);
+                }
+                const type = s.substring(0, dotIndex);
+                const name = s.substring(dotIndex + 1);
+                if (type !== source_1.Sources.BIGQUERY_DATASET) {
+                    throw new Error(`Manifest error: Unsupported scope type in multiple scopes: '${type}'.`);
+                }
+                datasets.push(name);
+            }
+            source = await (0, source_1.createSource)(source_1.Sources.BIGQUERY_DATASET, datasets.join(','), ctx);
+        }
+        else {
+            const dotIndex = scope.indexOf('.');
+            if (dotIndex === -1) {
+                throw new Error(`Manifest error: scope '${scope}' is invalid.`);
+            }
+            source = await (0, source_1.createSource)(scope.substring(0, dotIndex), scope.substring(dotIndex + 1), ctx);
+        }
+        const snapshot = result.data.snapshot;
+        if (snapshot) {
+            if (snapshot.entries) {
+                for (const entryType of snapshot.entries) {
+                    const parts = entryType.split('.');
+                    if (parts.length !== 3) {
+                        throw new Error(`Manifest error: Invalid Entry Type '${entryType}'`);
+                    }
+                }
+            }
+            if (snapshot.aspects) {
+                for (const aspectType of snapshot.aspects) {
+                    const parts = aspectType.split('.');
+                    if (parts.length !== 3) {
+                        throw new Error(`Manifest error: Invalid Aspect Type '${aspectType}'`);
+                    }
+                }
+            }
+        }
+        const publishing = result.data.publishing;
+        if (publishing) {
+            if (publishing.entries) {
+                for (const entryType of publishing.entries) {
+                    const parts = entryType.split('.');
+                    if (parts.length !== 3) {
+                        throw new Error(`Manifest error: Invalid Entry Type '${entryType}'`);
+                    }
+                    if (!snapshot?.entries?.includes(entryType)) {
+                        throw new Error(`Manifest error: Publishing entry type '${entryType}' is not listed in snapshot entries.`);
+                    }
+                }
+            }
+            if (publishing.aspects) {
+                for (const aspectType of publishing.aspects) {
+                    const parts = aspectType.split('.');
+                    if (parts.length !== 3) {
+                        throw new Error(`Manifest error: Invalid Aspect Type '${aspectType}'`);
+                    }
+                    if (!snapshot?.aspects?.includes(aspectType)) {
+                        throw new Error(`Manifest error: Publishing aspect type '${aspectType}' is not listed in snapshot aspects.`);
+                    }
+                }
+            }
+        }
+        return new CatalogManifest(source, snapshot, publishing, layout);
+    }
+    save(path) {
+        let scope;
+        const names = this.source.name.split(',');
+        if (names.length > 1) {
+            scope = names.map(n => `${this.source.type}.${n}`);
+        }
+        else {
+            scope = `${this.source.type}.${this.source.name}`;
+        }
+        const data = {
+            scope: scope,
+            layout: this.layout ?? undefined,
+            snapshot: this.snapshotConfig ?? undefined,
+            publishing: this.publishingConfig ?? undefined
+        };
+        fs.writeFileSync(path, yaml.stringify(data), 'utf8');
+    }
+}
+exports.CatalogManifest = CatalogManifest;

package/build/ts/kcmd/metadata.d.ts

@@ -0,0 +1,25 @@
+export declare const OVERVIEW_ASPECT = "dataplex-types.global.overview";
+export interface Aspect {
+    [key: string]: any;
+}
+export interface Entry {
+    name: string;
+    type: string;
+    resource: {
+        name?: string;
+        system?: string;
+        platform?: string;
+        displayName?: string;
+        description?: string;
+        labels?: Record<string, string>;
+        location?: string;
+        parent?: string;
+        ancestors?: {
+            name: string;
+            type: string;
+        }[];
+        createTime?: string;
+        updateTime?: string;
+    };
+    aspects?: Record<string, Aspect>;
+}

package/build/ts/kcmd/metadata.js

@@ -0,0 +1,8 @@
+"use strict";
+// Defines metadata objects provided by the catalog snapshot
+//
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OVERVIEW_ASPECT = void 0;
+// The aspect that holds an entry's overview text, which the documents layout
+// writes as a document's body.
+exports.OVERVIEW_ASPECT = 'dataplex-types.global.overview';

package/build/ts/kcmd/okf/catalog_residue.d.ts

@@ -0,0 +1,14 @@
+import * as dataplex from '../gcp/dataplex';
+export declare const RESIDUE_VERSION = 1;
+export declare const OVERVIEW_ASPECT_KEY = "dataplex-types.global.overview";
+export declare const DOCUMENT_ASPECT_KEY = "dataplex-types.global.document";
+export declare const QUERY_TEMPLATE_ASPECT_KEY = "dataplex-types.global.query-template";
+export declare const DEFAULT_DOCUMENT_ENTRY_TYPE = "projects/dataplex-types/locations/global/entryTypes/document";
+export declare const QUERY_TEMPLATE_ENTRY_TYPE = "projects/dataplex-types/locations/global/entryTypes/query-template";
+export declare class ResidueError extends Error {
+}
+/** The aspect whose `type` field becomes the concept's OKF `type`. */
+export declare function typeFacetKey(entryType?: string): string | undefined;
+/** Collects what OKF cannot express. Undefined when there is nothing. */
+export declare function buildResidue(entry: dataplex.Entry, overviewAspectKey: string, body?: string): Record<string, unknown> | undefined;
+export declare function assertResidueOnly(frontmatter: Record<string, unknown>): void;

package/build/ts/kcmd/okf/catalog_residue.js

@@ -0,0 +1,124 @@
+"use strict";
+// Catalog fields OKF has no key for stored in the `x-kcmd` frontmatter block
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResidueError = exports.QUERY_TEMPLATE_ENTRY_TYPE = exports.DEFAULT_DOCUMENT_ENTRY_TYPE = exports.QUERY_TEMPLATE_ASPECT_KEY = exports.DOCUMENT_ASPECT_KEY = exports.OVERVIEW_ASPECT_KEY = exports.RESIDUE_VERSION = void 0;
+exports.typeFacetKey = typeFacetKey;
+exports.buildResidue = buildResidue;
+exports.assertResidueOnly = assertResidueOnly;
+const concept_1 = require("./concept");
+exports.RESIDUE_VERSION = 1;
+exports.OVERVIEW_ASPECT_KEY = 'dataplex-types.global.overview';
+exports.DOCUMENT_ASPECT_KEY = 'dataplex-types.global.document';
+exports.QUERY_TEMPLATE_ASPECT_KEY = 'dataplex-types.global.query-template';
+exports.DEFAULT_DOCUMENT_ENTRY_TYPE = 'projects/dataplex-types/locations/global/entryTypes/document';
+exports.QUERY_TEMPLATE_ENTRY_TYPE = 'projects/dataplex-types/locations/global/entryTypes/query-template';
+class ResidueError extends Error {
+}
+exports.ResidueError = ResidueError;
+const NATIVE_PATHS = [
+    ['entrySource.displayName', 'title'],
+    ['entrySource.description', 'description'],
+    ['entrySource.resource', 'resource'],
+];
+/** The aspect whose `type` field becomes the concept's OKF `type`. */
+function typeFacetKey(entryType) {
+    const short = entryType?.split('/').pop();
+    return short ? `dataplex-types.global.${short}` : undefined;
+}
+function liftedType(data) {
+    return typeof data?.['type'] === 'string' && data['type'] !== '';
+}
+/** Collects what OKF cannot express. Undefined when there is nothing. */
+function buildResidue(entry, overviewAspectKey, body) {
+    const residue = {};
+    if (entry.entryType)
+        residue['entryType'] = entry.entryType;
+    if (entry.parentEntry)
+        residue['parentEntry'] = entry.parentEntry;
+    const source = entry.entrySource ?? {};
+    const carried = {};
+    if (source.system)
+        carried['system'] = source.system;
+    if (source.platform)
+        carried['platform'] = source.platform;
+    if (source.location)
+        carried['location'] = source.location;
+    if (source.ancestors?.length)
+        carried['ancestors'] = source.ancestors;
+    if (source.labels && Object.keys(source.labels).length) {
+        carried['labels'] = source.labels;
+    }
+    if (Object.keys(carried).length)
+        residue['entrySource'] = carried;
+    // An OKF file always ends in a newline, so a body that does not must say so.
+    // This is the body as written to disk, after any trailing section is split
+    // off, since that is what push has to reconstruct.
+    const content = body ?? entry.aspects?.[overviewAspectKey]?.data?.['content'];
+    if (typeof content === 'string' && content && !content.endsWith('\n')) {
+        residue['trailingNewline'] = false;
+    }
+    const facetKey = typeFacetKey(entry.entryType);
+    const aspects = {};
+    for (const [key, aspect] of Object.entries(entry.aspects ?? {})) {
+        if (key === overviewAspectKey)
+            continue;
+        if (key === facetKey && liftedType(aspect.data)) {
+            const { type, ...rest } = aspect.data;
+            aspects[key] = rest;
+            continue;
+        }
+        aspects[key] = aspect.data;
+    }
+    if (Object.keys(aspects).length)
+        residue['aspects'] = aspects;
+    if (!Object.keys(residue).length)
+        return undefined;
+    return { v: exports.RESIDUE_VERSION, ...residue };
+}
+function at(obj, dotted) {
+    let cur = obj;
+    for (const part of dotted.split('.')) {
+        if (cur === null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[part];
+    }
+    return cur;
+}
+function assertResidueOnly(frontmatter) {
+    const rawExtra = frontmatter[concept_1.EXTRA_KEY];
+    if (rawExtra !== undefined &&
+        rawExtra !== null &&
+        (typeof rawExtra !== 'object' || Array.isArray(rawExtra))) {
+        throw new ResidueError(`${concept_1.EXTRA_KEY} must be a mapping`);
+    }
+    const raw = frontmatter[concept_1.RESIDUE_KEY];
+    if (raw === undefined || raw === null)
+        return;
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ResidueError(`${concept_1.RESIDUE_KEY} must be a mapping`);
+    }
+    const residue = raw;
+    const found = [];
+    for (const key of concept_1.KEY_ORDER) {
+        if (residue[key] !== undefined)
+            found.push(`${concept_1.RESIDUE_KEY}.${key} (${key})`);
+    }
+    for (const [dotted, native] of NATIVE_PATHS) {
+        if (at(residue, dotted) !== undefined) {
+            found.push(`${concept_1.RESIDUE_KEY}.${dotted} (${native})`);
+        }
+    }
+    const entryType = residue['entryType'];
+    const facetKey = typeFacetKey(typeof entryType === 'string' ? entryType : undefined);
+    const facet = facetKey
+        ? at(residue, 'aspects')?.[facetKey]
+        : undefined;
+    if (facet &&
+        typeof facet === 'object' &&
+        facet['type'] !== undefined) {
+        found.push(`${concept_1.RESIDUE_KEY}.aspects.${facetKey}.type (type)`);
+    }
+    if (found.length) {
+        throw new ResidueError(`residue duplicates native keys: ${found.join(', ')}`);
+    }
+}

package/build/ts/kcmd/okf/concept.d.ts

@@ -0,0 +1,14 @@
+/** One concept. The `id` is its path in the bundle, without `.md`. */
+export interface Concept {
+    id: string;
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export declare const RESIDUE_KEY = "x-kcmd";
+export declare const EXTRA_KEY = "extra";
+export declare const ENTRY_SOURCE_KEYS: readonly ["title", "description", "resource"];
+export declare const OKF_METADATA_KEYS: readonly ["tags", "status", "superseded_by", "stale_after", "runtime", "parameters", "computation", "executor", "attester", "generated", "verified", "sources", "usage_window"];
+export declare const KEY_ORDER: readonly string[];
+export declare function fileContentToConcept(text: string, id: string): Concept;
+/** Renders a concept back into file content. */
+export declare function conceptToFileContent(concept: Concept): string;