@google-cloud/kcmd 0.1.0 → 0.2.0

package/build/ts/kcmd/gcp/biglake.d.ts

@@ -11,6 +11,8 @@ export interface Catalog {
     [key: string]: any;
 }
 export declare class BigLakeClient extends api.ApiClient {
+    private readonly hive;
     constructor(ctx: context.ApiContext);
     getCatalog(project: string, catalog: string): Promise<api.ApiResult<Catalog>>;
+    getHiveCatalog(project: string, catalog: string): Promise<api.ApiResult<Catalog>>;
 }

package/build/ts/kcmd/gcp/biglake.js

@@ -1,7 +1,7 @@
 "use strict";
-// API client for BigLake, covering the one call the source check needs:
-// reading an Iceberg REST catalog, whose region decides where Knowledge
-// Catalog keeps the entries of its tables.
+// API client for BigLake, covering the calls the source check needs: reading
+// an Iceberg REST catalog or a Hive catalog, whose region decides where
+// Knowledge Catalog keeps the entries of its tables.
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -39,12 +39,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BigLakeClient = void 0;
 const api = __importStar(require("./api"));
 class BigLakeClient extends api.ApiClient {
+    hive;
     constructor(ctx) {
         super('https://biglake.googleapis.com', 'iceberg/v1/restcatalog/extensions', ctx);
+        this.hive =
+            new api.ApiClient('https://biglake.googleapis.com', 'hive/v1', ctx);
     }
-    // Fetches a catalog. A catalog that does not exist answers 404.
+    // Fetches an Iceberg REST catalog. A catalog that does not exist answers
+    // 404, and a Hive catalog answers 400.
     async getCatalog(project, catalog) {
         return await this._get(`projects/${project}/catalogs/${catalog}`);
     }
+    // Fetches a Hive catalog. Any other catalog answers 404, and an id that is
+    // not lower-case letters, digits and underscores answers 400.
+    async getHiveCatalog(project, catalog) {
+        return await this.hive._get(`projects/${project}/catalogs/${catalog}`);
+    }
 }
 exports.BigLakeClient = BigLakeClient;

package/build/ts/kcmd/gcp/spanner.d.ts

@@ -35,7 +35,16 @@ export interface SpannerType {
 }
 export interface Instance {
     name?: string;
+    edition?: string;
     config?: string;
+    replicaComputeCapacity?: Array<{
+        replicaSelection?: {
+            location?: string;
+        };
+        processingUnits?: number;
+        nodeCount?: number;
+    }>;
+    resourceLocation?: string;
     [key: string]: any;
 }
 export interface InstanceConfig {
@@ -52,6 +61,7 @@ export declare class SpannerClient extends api.ApiClient {
     updateDatabaseDdl(project: string, instance: string, database: string, statements: string[]): Promise<api.ApiResult<Operation>>;
     getDatabase(project: string, instance: string, database: string): Promise<api.ApiResult<{
         name?: string;
+        databaseDialect?: string;
         [key: string]: any;
     }>>;
     getInstance(project: string, instance: string): Promise<api.ApiResult<Instance>>;

package/build/ts/kcmd/gcp/spanner.js

@@ -4,7 +4,8 @@
 // database and deploy Spanner Graph DDL; the data plane (sessions and
 // executeSql) to PLAN an action's DML against the live database before
 // publishing it; and Instance Admin (getInstance and getInstanceConfig) to
-// find the region where Knowledge Catalog keeps a table's entry.
+// find the region where Knowledge Catalog keeps a table's entry and to read an
+// instance's edition.
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -54,11 +55,13 @@ class SpannerClient extends api.ApiClient {
         const name = `projects/${project}/instances/${instance}/databases/${database}/ddl`;
         return await this._patch(name, { statements });
     }
-    // Fetches a database's metadata.
+    // Fetches a database's metadata, which includes its databaseDialect:
+    // GOOGLE_STANDARD_SQL or POSTGRESQL.
     async getDatabase(project, instance, database) {
         return await this._get(`projects/${project}/instances/${instance}/databases/${database}`);
     }
-    // Fetches an instance's metadata, which names its instance config.
+    // Fetches an instance's metadata, which names its instance config and its
+    // edition.
     async getInstance(project, instance) {
         return await this._get(`projects/${project}/instances/${instance}`);
     }

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

@@ -51,14 +51,36 @@ function mapping(value) {
 function text(value) {
     return typeof value === 'string' && value !== '' ? value : undefined;
 }
-function conceptFiles(dir) {
+function conceptFiles(dir, realRoot) {
+    const root = realRoot ?? fs.realpathSync(dir);
     return fs
         .readdirSync(dir, { withFileTypes: true })
         .sort((a, b) => a.name.localeCompare(b.name))
         .flatMap((e) => {
+        // OKF v0.3 §3.2(4): dot-prefixed files and directories are not part of the bundle.
+        if (e.name.startsWith('.'))
+            return [];
         const p = path.join(dir, e.name);
+        if (e.isSymbolicLink()) {
+            // OKF v0.3 §3.2(5): do not follow symlinks that resolve outside the bundle root.
+            let realTarget;
+            let stat;
+            try {
+                realTarget = fs.realpathSync(p);
+                stat = fs.statSync(p);
+            }
+            catch {
+                return [];
+            }
+            if (realTarget !== root && !realTarget.startsWith(root + path.sep)) {
+                return [];
+            }
+            if (stat.isDirectory())
+                return conceptFiles(p, root);
+            return e.name.endsWith('.md') ? [p] : [];
+        }
         if (e.isDirectory())
-            return conceptFiles(p);
+            return conceptFiles(p, root);
         return e.name.endsWith('.md') ? [p] : [];
     });
 }
@@ -67,8 +89,9 @@ function toPosixId(root, file) {
 }
 /**
  * Resolves the catalog entry ID a concept file maps to, or `undefined` when the
- * file should be skipped (`<group>_entry`, append-only `log.md`, or a generated
- * `index.md` shadowed by an explicit `agents.md` / `<dir>.md`).
+ * file should be skipped (`<group>_entry`, reserved `log.md` at any level,
+ * untyped non-concept `.md` files per OKF v0.3 §3.2, or a generated `index.md`
+ * shadowed by an explicit `agents.md` / `<dir>.md`).
  */
 function resolvedEntryName(id, frontmatter, bundlePath) {
     const residue = mapping(frontmatter[concept_1.RESIDUE_KEY]);
@@ -77,11 +100,17 @@ function resolvedEntryName(id, frontmatter, bundlePath) {
         text(extra['type'])?.endsWith('/entrygroup')) {
         return undefined;
     }
+    const hasConceptType = text(frontmatter['type']) !== undefined ||
+        text(residue['entryType']) !== undefined ||
+        text(extra['type']) !== undefined;
     const hasExplicitMeta = frontmatter[concept_1.RESIDUE_KEY] !== undefined ||
         frontmatter[concept_1.EXTRA_KEY] !== undefined ||
-        frontmatter['type'] !== undefined;
-    // Skip append-only operation logs (`log.md`) that carry no concept frontmatter.
-    if (id === 'log' && !hasExplicitMeta) {
+        hasConceptType;
+    // OKF v0.3 §§3.1, 9: `log.md` at any level is a reserved history file, never
+    // a concept, unless it is a pulled remote entry carrying `x-kcmd` / `extra`.
+    if ((id === 'log' || id.endsWith('/log')) &&
+        frontmatter[concept_1.RESIDUE_KEY] === undefined &&
+        frontmatter[concept_1.EXTRA_KEY] === undefined) {
         return undefined;
     }
     // When `agents.md` or `<dir>.md` already exists alongside a directory-listing
@@ -96,6 +125,13 @@ function resolvedEntryName(id, frontmatter, bundlePath) {
         fs.existsSync(path.join(bundlePath, `${id.slice(0, -'/index'.length)}.md`))) {
         return undefined;
     }
+    // OKF v0.3 §3.2(2): a non-index `.md` file with no `type` in frontmatter
+    // (e.g. `README.md`, `AGENTS.md`, `CONTRIBUTING.md`, `SKILL.md`) is not a
+    // concept; consumers skip it rather than rejecting the bundle.
+    const isIndex = id === 'index' || id.endsWith('/index');
+    if (!isIndex && !hasConceptType) {
+        return undefined;
+    }
     const explicitId = text(residue['entryId']) ?? text(extra['entry_id']);
     if (explicitId)
         return explicitId;
@@ -292,10 +328,16 @@ class OkfLayout {
         return (0, concept_to_entry_1.entryToConcept)(gcpEntry, name);
     }
     async saveEntry(name, entry) {
+        const prevFile = this._index.get(name);
         const file = this.resolveConceptPath(name);
         const concept = this.previewConcept(name, entry);
         await fs.promises.mkdir(path.dirname(file), { recursive: true });
         await fs.promises.writeFile(file, (0, concept_1.conceptToFileContent)(concept), 'utf8');
+        if (prevFile &&
+            path.resolve(prevFile) !== path.resolve(file) &&
+            fs.existsSync(prevFile)) {
+            await fs.promises.unlink(prevFile);
+        }
         this._index.set(name, file);
     }
     async deleteEntry(name) {

package/build/ts/kcmd/layouts/semantic-model.d.ts

@@ -4,6 +4,7 @@ export declare function profileFilesBeside(dir: string, model: string): {
     name: string;
     path: string;
 }[];
+export declare function profileFileNamesBeside(dir: string, model: string): string[];
 export interface OverviewSidecar {
     content?: string;
     contentType?: string;
@@ -12,6 +13,12 @@ export interface OverviewSidecar {
         title?: string;
     }>;
 }
+export declare function vanillaSiblingError(file: string, modelFile: string): string;
+export declare function legacyProfileFiles(dir: string, model: string): {
+    name: string;
+    path: string;
+}[];
+export declare function legacyProfileDirError(model: string): string;
 export declare class SemanticModelLayout implements CatalogLayout {
     private readonly _catalogPath;
     private readonly _entryGroup?;
@@ -28,6 +35,7 @@ export declare class SemanticModelLayout implements CatalogLayout {
         path: string;
         profileName?: string;
     }[];
+    profileFilePaths(model: string): string[];
     overviewSidecars(): Map<string, OverviewSidecar>;
     overviewSidecarPaths(): {
         entryId: string;
@@ -59,3 +67,8 @@ export declare class SemanticModelLayout implements CatalogLayout {
 export declare function fileNameOf(layout: SemanticModelLayout, model: string, localPath: string): string;
 export declare function parseOverviewSidecar(text: string, file: string): OverviewSidecar;
 export declare function formatOverviewSidecar({ content, ...rest }: OverviewSidecar): string;
+export declare class ProfileFileError extends Error {
+}
+export declare function checkProfileFileName(modelFile: string, file: string, name: string, text: string, seen: Map<string, string>): void;
+export declare function profileNameError(file: string, name: string): string | undefined;
+export declare function profileParseError(file: string, message: string): string;

package/build/ts/kcmd/layouts/semantic-model.js

@@ -42,11 +42,18 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SemanticModelLayout = void 0;
+exports.ProfileFileError = exports.SemanticModelLayout = void 0;
 exports.profileFilesBeside = profileFilesBeside;
+exports.profileFileNamesBeside = profileFileNamesBeside;
+exports.vanillaSiblingError = vanillaSiblingError;
+exports.legacyProfileFiles = legacyProfileFiles;
+exports.legacyProfileDirError = legacyProfileDirError;
 exports.fileNameOf = fileNameOf;
 exports.parseOverviewSidecar = parseOverviewSidecar;
 exports.formatOverviewSidecar = formatOverviewSidecar;
+exports.checkProfileFileName = checkProfileFileName;
+exports.profileNameError = profileNameError;
+exports.profileParseError = profileParseError;
 const glob = __importStar(require("glob"));
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -82,6 +89,22 @@ function profileFilesBeside(dir, model) {
     }
     return out.sort((a, b) => a.name.localeCompare(b.name));
 }
+// Each `<model>.profile.*.yaml` in `dir`, whatever its profile name: the
+// nameless file first, then those whose profile name is empty or has a dot, by
+// file name, then the rest by profile name.
+function profileFileNamesBeside(dir, model) {
+    if (!fs.existsSync(dir))
+        return [];
+    const named = profileFilesBeside(dir, model).map(p => path.basename(p.path));
+    const nameless = `${model}.profile.yaml`;
+    const others = fs.readdirSync(dir).filter(f => f.startsWith(`${model}.profile.`) && f.endsWith('.yaml') &&
+        f !== nameless && !named.includes(f));
+    return [
+        ...(fs.existsSync(path.join(dir, nameless)) ? [nameless] : []),
+        ...others.sort(),
+        ...named,
+    ];
+}
 // The suffix of an entry's overview sidecar.
 const OVERVIEW_SIDECAR = '.overview.md';
 // The profile name reserved for the inline bindings in the model file.
@@ -89,14 +112,36 @@ const DEFAULT_PROFILE_NAME = 'default';
 // The flavor that keeps its profiles inline, in a GOOGLE block, and so has no
 // sibling profile files.
 const VANILLA_VERSION = '0.2.0.dev0';
-// The error for a sibling profile file beside a vanilla model, which keeps its
-// profiles in its GOOGLE block.
-function vanillaSiblingError(file, model) {
-    return `Profile file '${file}' sits beside '${model}.yaml', which is a ` +
+// Push's error for the profile file `file` beside the vanilla model file
+// `modelFile`, which keeps its profiles in its GOOGLE block.
+function vanillaSiblingError(file, modelFile) {
+    return `Profile file '${file}' sits beside '${modelFile}', which is a ` +
         `${VANILLA_VERSION} document; sibling profile files are Google-flavor ` +
         `only, and a ${VANILLA_VERSION} model keeps its profiles in its GOOGLE ` +
         `block.`;
 }
+// The profile files in the older `<model>.profiles/` directory in `dir`, each
+// named by its file basename.
+function legacyProfileFiles(dir, model) {
+    const legacy = path.join(dir, `${model}.profiles`);
+    if (!fs.statSync(legacy, { throwIfNoEntry: false })?.isDirectory())
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(legacy)) {
+        if (!entry.endsWith('.yaml'))
+            continue;
+        if (SIDECAR_SUFFIXES.some(s => entry.endsWith(s)))
+            continue;
+        out.push({ name: path.basename(entry, '.yaml'), path: path.join(legacy, entry) });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+// Push's error for the older `<model>.profiles/` directory.
+function legacyProfileDirError(model) {
+    return `Legacy profile directory '${model}.profiles/' is no longer ` +
+        `supported; rename profile files to '${model}.profile.<name>.yaml' ` +
+        `beside '${model}.yaml'.`;
+}
 class SemanticModelLayout {
     _catalogPath;
     _entryGroup;
@@ -179,6 +224,18 @@ class SemanticModelLayout {
             ...this._legacyProfilePaths(model).map(p => ({ path: p.path })),
         ];
     }
+    // Every profile file of a model on disk, whatever its profile name: each
+    // `<model>.profile.*.yaml` in the entry group, as profileFileNamesBeside
+    // lists them, then each file in the older `<model>.profiles/` directory.
+    profileFilePaths(model) {
+        if (!this._entryGroup)
+            return [];
+        const dir = this._groupDir();
+        return [
+            ...profileFileNamesBeside(dir, model).map(f => path.join(dir, f)),
+            ...this._legacyProfilePaths(model).map(p => p.path),
+        ];
+    }
     // The overview sidecar of each entry, by entry id. Throws naming a sidecar
     // parseOverviewSidecar rejects.
     overviewSidecars() {
@@ -218,8 +275,7 @@ class SemanticModelLayout {
             path.join(this._groupDir(), `${model}.profile.yaml`) :
             undefined;
         if (nameless && fs.existsSync(nameless)) {
-            throw new Error(`Profile file '${path.basename(nameless)}' names no profile; ` +
-                `rename it '${model}.profile.<name>.yaml'.`);
+            throw new Error(profileNameError(path.basename(nameless), ''));
         }
         const prefix = `${model}.profile.`;
         const badName = this._entryGroup && fs.existsSync(this._groupDir()) ?
@@ -232,9 +288,7 @@ class SemanticModelLayout {
             }) :
             undefined;
         if (badName) {
-            throw new Error(`Profile file '${badName}' has profile name '${badName.slice(prefix.length, -'.yaml'.length)}'; a profile ` +
-                `name is a letter followed by letters, digits, underscores and ` +
-                `hyphens.`);
+            throw new Error(profileNameError(badName, badName.slice(prefix.length, -'.yaml'.length)));
         }
         const siblings = this._siblingProfilePaths(model);
         if (!siblings.length)
@@ -253,40 +307,17 @@ class SemanticModelLayout {
         }
         const version = header.version;
         const docs = [];
-        // Profile names are unique ignoring case.
-        const byLowerName = new Map();
+        const seen = new Map();
         for (const { name, path: p } of siblings) {
             const file = path.basename(p);
-            const twin = byLowerName.get(name.toLowerCase());
-            if (twin) {
-                throw new Error(`Profile files '${twin}' and '${file}' name the same profile; ` +
-                    `profile names are unique ignoring case.`);
-            }
-            byLowerName.set(name.toLowerCase(), file);
             if (!fs.statSync(p).isFile()) {
                 throw new Error(`Profile file '${file}' is not a file.`);
             }
             if (version === VANILLA_VERSION) {
-                throw new Error(vanillaSiblingError(file, model));
+                throw new Error(vanillaSiblingError(file, modelFile));
             }
             const text = fs.readFileSync(p, 'utf8');
-            const declared = parseProfileName(text, file, name);
-            const reserved = (n) => n?.toLowerCase() === DEFAULT_PROFILE_NAME;
-            if (reserved(name)) {
-                throw new Error(`Profile name '${DEFAULT_PROFILE_NAME}' is reserved for the ` +
-                    `inline bindings in '${modelFile}'; remove '${file}'.`);
-            }
-            if (reserved(declared)) {
-                throw new Error(`Profile name '${DEFAULT_PROFILE_NAME}' is reserved for the ` +
-                    `inline bindings in '${modelFile}'; change the name in '${file}' to '${name}'.`);
-            }
-            if (declared === undefined) {
-                throw new Error(`Profile file '${file}' declares no name; add 'name: ${name}'.`);
-            }
-            if (declared !== name) {
-                throw new Error(`Profile file '${file}' declares name '${declared}', which ` +
-                    `does not match filename suffix '${name}'.`);
-            }
+            checkProfileFileName(modelFile, file, name, text, seen);
             docs.push({ name, text, path: p });
         }
         return docs;
@@ -376,18 +407,7 @@ class SemanticModelLayout {
     _legacyProfilePaths(model) {
         if (!this._entryGroup || /[\\/]/.test(model))
             return [];
-        const dir = path.join(this._groupDir(), `${model}.profiles`);
-        if (!fs.existsSync(dir))
-            return [];
-        const out = [];
-        for (const entry of fs.readdirSync(dir)) {
-            if (!entry.endsWith('.yaml'))
-                continue;
-            if (SIDECAR_SUFFIXES.some(s => entry.endsWith(s)))
-                continue;
-            out.push({ name: path.basename(entry, '.yaml'), path: path.join(dir, entry) });
-        }
-        return out.sort((a, b) => a.name.localeCompare(b.name));
+        return legacyProfileFiles(this._groupDir(), model);
     }
     // The `version` and model `name` a model document declares, each undefined
     // when the document has none. In a document with a YAML error, the version
@@ -520,6 +540,65 @@ function formatOverviewSidecar({ content = '', ...rest }) {
         (0, documents_1.joinFrontmatter)(rest, body) :
         body;
 }
+// The error checkProfileFileName throws for a profile file that breaks one of
+// its rules.
+class ProfileFileError extends Error {
+}
+exports.ProfileFileError = ProfileFileError;
+// Throws when the profile file `file`, holding `text` for profile `name` beside
+// the model file `modelFile`, names the same profile as a file in `seen`, which
+// maps each profile name read before, in lower case, to its file. It also
+// throws when the name breaks the naming rule, the file does not parse, uses
+// the legacy `semantic_model:` wrapper, takes the name reserved for the inline
+// bindings, or declares no name or another name. Adds the file to `seen`.
+function checkProfileFileName(modelFile, file, name, text, seen) {
+    const badName = profileNameError(file, name);
+    if (badName)
+        throw new ProfileFileError(badName);
+    // Profile names are unique ignoring case.
+    const twin = seen.get(name.toLowerCase());
+    if (twin) {
+        throw new ProfileFileError(`Profile files '${twin}' and '${file}' name the same profile; ` +
+            `profile names are unique ignoring case.`);
+    }
+    seen.set(name.toLowerCase(), file);
+    const declared = parseProfileName(text, file, name);
+    const reserved = (n) => n?.toLowerCase() === DEFAULT_PROFILE_NAME;
+    if (reserved(name)) {
+        throw new ProfileFileError(`Profile name '${DEFAULT_PROFILE_NAME}' is reserved for the ` +
+            `inline bindings in '${modelFile}'; remove '${file}'.`);
+    }
+    if (reserved(declared)) {
+        throw new ProfileFileError(`Profile name '${DEFAULT_PROFILE_NAME}' is reserved for the ` +
+            `inline bindings in '${modelFile}'; change the name in '${file}' to ` +
+            `'${name}'.`);
+    }
+    if (declared === undefined) {
+        throw new ProfileFileError(`Profile file '${file}' declares no name; add 'name: ${name}'.`);
+    }
+    if (declared !== name) {
+        throw new ProfileFileError(`Profile file '${file}' declares name '${declared}', which does not ` +
+            `match filename suffix '${name}'.`);
+    }
+}
+// Push's error for the profile file `file` whose profile name `name` breaks
+// the naming rule, or undefined. A `<model>.profile.yaml` names no profile.
+function profileNameError(file, name) {
+    const nameless = file.match(/^(.*)\.profile\.yaml$/);
+    if (nameless && name === '') {
+        return `Profile file '${file}' names no profile; rename it ` +
+            `'${nameless[1]}.profile.<name>.yaml'.`;
+    }
+    if ((0, names_1.nameProblem)('profile', name) === undefined)
+        return undefined;
+    return `Profile file '${file}' has profile name '${name}'; a profile name ` +
+        `is a letter followed by letters, digits, underscores and hyphens.`;
+}
+// Push's error for the profile file `file`, which does not parse, with the
+// parser's `message`.
+function profileParseError(file, message) {
+    return `Profile file '${file}' does not parse: ${message}`;
+}
 // The `name` a profile file declares at its top level, or undefined when it
 // declares none. A file that does not parse or that uses the legacy
 // `semantic_model:` wrapper throws, naming the file.
@@ -529,10 +608,10 @@ function parseProfileName(text, file, name) {
         doc = yaml.parse(text, yaml_options_1.YAML_OPTIONS);
     }
     catch (err) {
-        throw new Error(`Profile file '${file}' does not parse: ${err?.message ?? err}`);
+        throw new ProfileFileError(profileParseError(file, err?.message ?? err));
     }
     if (doc?.semantic_model !== undefined) {
-        throw new Error(`Profile file '${file}' uses the legacy 'semantic_model:' wrapper, ` +
+        throw new ProfileFileError(`Profile file '${file}' uses the legacy 'semantic_model:' wrapper, ` +
             `which is no longer supported; write its entities, relationships ` +
             `and actions at the top level under 'name: ${name}', and move any ` +
             `'deployment_target' to an entry under 'deployments:' in the model ` +

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

@@ -7,7 +7,7 @@ export interface Concept {
 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", "stale_after", "generated", "verified", "sources", "usage_window"];
+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. */

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

@@ -44,7 +44,13 @@ exports.ENTRY_SOURCE_KEYS = ['title', 'description', 'resource'];
 exports.OKF_METADATA_KEYS = [
     'tags',
     'status',
+    'superseded_by',
     'stale_after',
+    'runtime',
+    'parameters',
+    'computation',
+    'executor',
+    'attester',
     'generated',
     'verified',
     'sources',

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

@@ -2,6 +2,8 @@ import * as dataplex from '../gcp/dataplex';
 import { Concept } from './concept';
 export declare class ConceptError extends Error {
 }
+/** Valid Dataplex `query-template` aspect `parameters[].type` enum values. */
+export declare const VALID_QUERY_TEMPLATE_PARAM_TYPES: Set<string>;
 /** Maps OKF human-readable `type` labels to Dataplex `document.type` slugs. */
 export declare function normalizeOkfDocType(rawType: string): string;
 export declare function entryToConcept(entry: dataplex.Entry, id: string): Concept;

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

@@ -1,7 +1,7 @@
 "use strict";
 // Bidirectional conversion between a Dataplex `Entry` and an OKF `Concept`.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConceptError = void 0;
+exports.VALID_QUERY_TEMPLATE_PARAM_TYPES = exports.ConceptError = void 0;
 exports.normalizeOkfDocType = normalizeOkfDocType;
 exports.entryToConcept = entryToConcept;
 exports.conceptToEntry = conceptToEntry;
@@ -27,6 +27,18 @@ function headingTitle(body) {
     }
     return undefined;
 }
+/** Valid Dataplex `query-template` aspect `parameters[].type` enum values. */
+exports.VALID_QUERY_TEMPLATE_PARAM_TYPES = new Set([
+    'BOOLEAN',
+    'NUMBER',
+    'STRING',
+    'BYTES',
+    'DATETIME',
+    'TIMESTAMP',
+    'GEOSPATIAL',
+    'STRUCT',
+    'RANGE',
+]);
 /** Maps OKF human-readable `type` labels to Dataplex `document.type` slugs. */
 function normalizeOkfDocType(rawType) {
     const norm = rawType
@@ -34,6 +46,12 @@ function normalizeOkfDocType(rawType) {
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-|-$/g, '');
+    if (norm === 'context-set' || norm === 'knowledge-base-root') {
+        return 'context-set';
+    }
+    if (norm === 'knowledge-base-index' || norm === 'index') {
+        return 'knowledge-base-index';
+    }
     if (norm === 'table' ||
         norm === 'bigquery-table' ||
         norm === 'table-context') {
@@ -218,6 +236,10 @@ function conceptToEntry(concept, entryGroup) {
                 if (stripped.length) {
                     console.warn(`[kcmd] ${concept.id}: stripping unsupported parameter key(s) ${stripped.join(', ')} on parameters[${idx}]`);
                 }
+                const paramType = text(cleaned['type']);
+                if (paramType && !exports.VALID_QUERY_TEMPLATE_PARAM_TYPES.has(paramType)) {
+                    throw new ConceptError(`${concept.id}: ${catalog_residue_1.QUERY_TEMPLATE_ASPECT_KEY}.parameters[${idx}].type '${paramType}' is invalid; must be one of ${[...exports.VALID_QUERY_TEMPLATE_PARAM_TYPES].join(', ')}`);
+                }
                 return cleaned;
             });
         }
@@ -234,7 +256,12 @@ function conceptToEntry(concept, entryGroup) {
         facetKey in aspects &&
         (facetKey === catalog_residue_1.DOCUMENT_ASPECT_KEY ||
             normalizeOkfDocType(conceptType) !== shortEntryType)) {
-        aspects[facetKey] = { data: { type: conceptType, ...aspects[facetKey].data } };
+        const resolvedType = facetKey === catalog_residue_1.DOCUMENT_ASPECT_KEY
+            ? normalizeOkfDocType(conceptType)
+            : conceptType;
+        aspects[facetKey] = {
+            data: { ...aspects[facetKey].data, type: resolvedType },
+        };
     }
     else if (conceptType &&
         !residueEntryType &&

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

@@ -76,18 +76,13 @@ async function initOkfWorkspace(ctx, manifest, options = {}) {
     const prior = fs.existsSync('catalog.yaml')
         ? fs.readFileSync('catalog.yaml', 'utf8')
         : undefined;
-    if (typeof manifest.save === 'function') {
-        manifest.save('catalog.yaml');
-    }
-    else {
-        const scopeType = manifest.source.type || 'entryGroup';
-        fs.writeFileSync('catalog.yaml', yaml.stringify({ scope: `${scopeType}.${scopeName}` }), 'utf8');
-    }
+    const scopeType = manifest.source.type || 'entryGroup';
+    fs.writeFileSync('catalog.yaml', yaml.stringify({ scope: `${scopeType}.${scopeName}`, layout: 'okf' }), 'utf8');
     const scope = scopeOf(fs.readFileSync('catalog.yaml', 'utf8'));
     if (prior !== undefined && scope !== undefined && scopeOf(prior) === scope) {
         fs.writeFileSync('catalog.yaml', prior);
+        (0, manifest_1.writeWorkspaceLayout)('catalog.yaml', 'okf');
     }
-    (0, manifest_1.writeWorkspaceLayout)('catalog.yaml', 'okf');
     console.log(fs.readFileSync('catalog.yaml', 'utf8').trimEnd());
     const remoteExists = manifest.okfRemoteExists === true;
     const shouldPull = (options.pull && remoteExists) ||
@@ -108,8 +103,11 @@ async function initOkfWorkspace(ctx, manifest, options = {}) {
     fs.mkdirSync(okf_1.BUNDLE_DIR, { recursive: true });
     const indexPath = path.join(okf_1.BUNDLE_DIR, 'index.md');
     const agentsPath = path.join(okf_1.BUNDLE_DIR, 'agents.md');
-    if (!fs.existsSync(indexPath) && !fs.existsSync(agentsPath)) {
-        fs.writeFileSync(indexPath, `---\nokf_version: "0.2"\n---\n# ${groupId}\n`, 'utf8');
+    const hasConceptFiles = fs
+        .readdirSync(okf_1.BUNDLE_DIR)
+        .some((f) => f.endsWith('.md'));
+    if (!fs.existsSync(indexPath) && !fs.existsSync(agentsPath) && !hasConceptFiles) {
+        fs.writeFileSync(indexPath, `---\nokf_version: "0.3"\n---\n# ${groupId}\n`, 'utf8');
     }
     return 0;
 }