@skmtc/core 0.0.983 → 0.16.1

package/esm/dsl/GeneratorKeys.js

@@ -17,64 +17,69 @@
  * - **Generator Organization**: Clear mapping between generators and their artifacts
  * - **Reference Integration**: Seamless integration with OpenAPI reference system
  *
- * @example Creating operation generator keys
+ * @example Creating an OAS operation generator key
  * ```typescript
- * import { toOperationGeneratorKey, parseOperationGeneratorKey } from '@skmtc/core/GeneratorKeys';
+ * import { toOasOperationGeneratorKey, fromGeneratorKey } from '@skmtc/core/GeneratorKeys';
  *
- * // Create a key for a GET /users operation in api-client generator
- * const key = toOperationGeneratorKey({
+ * const key = toOasOperationGeneratorKey({
  *   generatorId: 'api-client',
  *   path: '/users',
- *   method: 'GET'
+ *   method: 'get'
  * });
  *
- * // Parse the key back into components
- * const parsed = parseOperationGeneratorKey(key);
- * console.log(parsed); // { generatorId: 'api-client', path: '/users', method: 'GET' }
+ * const parsed = fromGeneratorKey(key);
+ * if (parsed.type === 'oasOperation') {
+ *   console.log(parsed); // { type: 'oasOperation', generatorId: 'api-client', path: '/users', method: 'get' }
+ * }
  * ```
  *
- * @example Working with model keys
+ * @example Creating a GraphQL operation generator key
  * ```typescript
- * import { toModelGeneratorKey } from '@skmtc/core/GeneratorKeys';
+ * import { toGqlOperationGeneratorKey, fromGeneratorKey } from '@skmtc/core/GeneratorKeys';
  *
- * const modelKey = toModelGeneratorKey({
- *   generatorId: 'typescript-models',
- *   refName: 'User' as RefName
+ * const key = toGqlOperationGeneratorKey({
+ *   generatorId: 'graphql-client',
+ *   rootKind: 'query',
+ *   fieldName: 'getUser'
  * });
+ *
+ * const parsed = fromGeneratorKey(key);
+ * if (parsed.type === 'gqlOperation') {
+ *   console.log(parsed); // { type: 'gqlOperation', generatorId: 'graphql-client', rootKind: 'query', fieldName: 'getUser' }
+ * }
  * ```
  *
- * @example Type-safe key handling
+ * @example Working with model keys
  * ```typescript
- * import type { OperationGeneratorKey, ModelGeneratorKey } from '@skmtc/core/GeneratorKeys';
- *
- * function handleOperationKey(key: OperationGeneratorKey) {
- *   // TypeScript ensures this is specifically an operation key
- *   const parsed = parseOperationGeneratorKey(key);
- *   return `Processing ${parsed.method} ${parsed.path}`;
- * }
+ * import { toModelGeneratorKey } from '@skmtc/core/GeneratorKeys';
+ * import type { RefName } from '@skmtc/core/RefName';
  *
- * function handleModelKey(key: ModelGeneratorKey) {
- *   // TypeScript ensures this is specifically a model key
- *   const parsed = parseModelGeneratorKey(key);
- *   return `Processing model ${parsed.refName}`;
- * }
+ * const modelKey = toModelGeneratorKey({
+ *   generatorId: 'typescript-models',
+ *   refName: 'User' as RefName,
+ *   variant: 'main'
+ * });
  * ```
  *
  * @module GeneratorKeys
  */
+import "../_dnt.polyfills.js";
 import { isMethod } from '../types/Method.js';
+const GQL_ROOT_KINDS = ['query', 'mutation', 'subscription'];
+const isGqlRootKind = (value) => GQL_ROOT_KINDS.includes(value);
 /**
- * Creates an operation generator key from generator ID and operation details.
+ * Creates an OAS operation generator key from generator ID and operation details.
  *
- * Operation generator keys uniquely identify generators processing specific
- * API operations. The key format is: `generatorId|path|method`
+ * Uniquely identifies a generator processing a specific API operation. The
+ * key format is: `generatorId|path|method`. See
+ * {@link toGqlOperationGeneratorKey} for the GraphQL counterpart.
  *
- * @param args - Operation generator key arguments
- * @returns A branded OperationGeneratorKey
+ * @param args - Key construction arguments
+ * @returns A branded OasOperationGeneratorKey
  *
  * @example With explicit path and method
  * ```typescript
- * const key = toOperationGeneratorKey({
+ * const key = toOasOperationGeneratorKey({
  *   generatorId: 'api-client',
  *   path: '/users/{id}',
  *   method: 'get'
@@ -90,23 +95,50 @@ import { isMethod } from '../types/Method.js';
  *   // ... other operation details
  * });
  *
- * const key = toOperationGeneratorKey({
+ * const key = toOasOperationGeneratorKey({
  *   generatorId: 'rest-client',
  *   operation
  * });
  * // Result: 'rest-client|/posts|post' (branded)
  * ```
  */
-export const toOperationGeneratorKey = ({ generatorId, ...rest }) => {
+export const toOasOperationGeneratorKey = ({ generatorId, variant, ...rest }) => {
     const { path, method } = 'operation' in rest ? rest.operation : rest;
-    const nakedKey = `${generatorId}|${path}|${method}`;
+    const nakedKey = `${generatorId}|${path}|${method}|${variant}`;
+    return nakedKey;
+};
+/**
+ * Creates a webhook generator key from generator ID and webhook details.
+ *
+ * Sibling to {@link toOasOperationGeneratorKey} for the 3.1 webhook subject.
+ * Format: `generatorId|webhook|name|method|variant`. The literal `webhook`
+ * segment keeps webhook keys from colliding with operation keys.
+ */
+export const toWebhookGeneratorKey = ({ generatorId, variant, ...rest }) => {
+    const { name, method } = 'webhook' in rest ? rest.webhook : rest;
+    const nakedKey = `${generatorId}|webhook|${name}|${method}|${variant}`;
     return nakedKey;
 };
 /**
- * Creates a model generator key from generator ID and schema reference name.
+ * Creates a GraphQL operation generator key.
+ *
+ * Sibling to {@link toOasOperationGeneratorKey} for the GraphQL protocol. Format:
+ * `generatorId|rootKind|fieldName|variant`.
+ */
+export const toGqlOperationGeneratorKey = ({ generatorId, variant, ...rest }) => {
+    const { rootKind, fieldName } = 'operation' in rest
+        ? { rootKind: rest.operation.rootKind, fieldName: rest.operation.fieldName }
+        : rest;
+    const nakedKey = `${generatorId}|${rootKind}|${fieldName}|${variant}`;
+    return nakedKey;
+};
+/**
+ * Creates a model generator key from generator ID, schema reference name,
+ * and variant.
  *
  * Model generator keys uniquely identify generators processing specific
- * OpenAPI schema models. The key format is: `generatorId|refName`
+ * OpenAPI schema models for a given variant. The key format is:
+ * `generatorId|refName|variant`.
  *
  * @param args - Model generator key arguments
  * @returns A branded ModelGeneratorKey
@@ -115,19 +147,21 @@ export const toOperationGeneratorKey = ({ generatorId, ...rest }) => {
  * ```typescript
  * const key = toModelGeneratorKey({
  *   generatorId: 'typescript-interfaces',
- *   refName: 'User'
+ *   refName: 'User',
+ *   variant: 'main'
  * });
- * // Result: 'typescript-interfaces|User' (branded)
+ * // Result: 'typescript-interfaces|User|main' (branded)
  *
- * const validationKey = toModelGeneratorKey({
+ * const coercive = toModelGeneratorKey({
  *   generatorId: 'zod-schemas',
- *   refName: 'CreateUserRequest'
+ *   refName: 'CreateUserRequest',
+ *   variant: 'coercive'
  * });
- * // Result: 'zod-schemas|CreateUserRequest' (branded)
+ * // Result: 'zod-schemas|CreateUserRequest|coercive' (branded)
  * ```
  */
-export const toModelGeneratorKey = ({ generatorId, refName }) => {
-    const nakedKey = `${generatorId}|${refName}`;
+export const toModelGeneratorKey = ({ generatorId, refName, variant }) => {
+    const nakedKey = `${generatorId}|${refName}|${variant}`;
     return nakedKey;
 };
 /**
@@ -178,41 +212,45 @@ export const toGeneratorOnlyKey = ({ generatorId }) => {
  * ```
  */
 export const isGeneratorKey = (arg) => {
-    return isModelGeneratorKey(arg) || isOperationGeneratorKey(arg) || isGeneratorOnlyKey(arg);
+    return (isModelGeneratorKey(arg) ||
+        isOasOperationGeneratorKey(arg) ||
+        isWebhookGeneratorKey(arg) ||
+        isGqlOperationGeneratorKey(arg) ||
+        isGeneratorOnlyKey(arg));
 };
 /**
- * Type guard to check if a value is a valid OperationGeneratorKey.
+ * Type guard to check if a value is a valid OasOperationGeneratorKey.
  *
  * Validates that the argument is a string with the correct format:
  * `generatorId|path|method` where each part is non-empty and method
  * is a valid HTTP method.
  *
  * @param arg - Value to check
- * @returns True if the value is a valid OperationGeneratorKey
+ * @returns True if the value is a valid OasOperationGeneratorKey
  *
  * @example
  * ```typescript
  * const key = 'api-client|/users/{id}|get';
  *
- * if (isOperationGeneratorKey(key)) {
- *   // key is now typed as OperationGeneratorKey
+ * if (isOasOperationGeneratorKey(key)) {
+ *   // key is now typed as OasOperationGeneratorKey
  *   const obj = fromGeneratorKey(key);
- *   console.log(obj.type);        // 'operation'
+ *   console.log(obj.type);        // 'oasOperation'
  *   console.log(obj.generatorId); // 'api-client'
  *   console.log(obj.path);        // '/users/{id}'
  *   console.log(obj.method);      // 'get'
  * }
  * ```
  */
-export const isOperationGeneratorKey = (arg) => {
+export const isOasOperationGeneratorKey = (arg) => {
     if (typeof arg !== 'string') {
         return false;
     }
     const keyTokens = arg.split('|');
-    if (keyTokens.length !== 3) {
+    if (keyTokens.length !== 4) {
         return false;
     }
-    const [generatorId, path, method] = keyTokens;
+    const [generatorId, path, method, variant] = keyTokens;
     if (typeof generatorId !== 'string' || !generatorId.length) {
         return false;
     }
@@ -222,6 +260,74 @@ export const isOperationGeneratorKey = (arg) => {
     if (!isMethod(method)) {
         return false;
     }
+    if (typeof variant !== 'string' || !variant.length) {
+        return false;
+    }
+    return true;
+};
+/**
+ * Type guard to check if a value is a valid {@link WebhookGeneratorKey}.
+ *
+ * Validates the format `generatorId|webhook|name|method|variant`: five
+ * pipe-delimited segments with a literal `webhook` discriminator in
+ * position 2, a valid HTTP method, and non-empty `generatorId` / `name` /
+ * `variant`. The 5-segment shape (and the `webhook` literal) is what keeps
+ * it disjoint from the 4-segment operation key.
+ */
+export const isWebhookGeneratorKey = (arg) => {
+    if (typeof arg !== 'string') {
+        return false;
+    }
+    const keyTokens = arg.split('|');
+    if (keyTokens.length !== 5) {
+        return false;
+    }
+    const [generatorId, discriminator, name, method, variant] = keyTokens;
+    if (typeof generatorId !== 'string' || !generatorId.length) {
+        return false;
+    }
+    if (discriminator !== 'webhook') {
+        return false;
+    }
+    if (typeof name !== 'string' || !name.length) {
+        return false;
+    }
+    if (!isMethod(method)) {
+        return false;
+    }
+    if (typeof variant !== 'string' || !variant.length) {
+        return false;
+    }
+    return true;
+};
+/**
+ * Type guard to check if a value is a valid {@link GqlOperationGeneratorKey}.
+ *
+ * Validates that the argument is a string with the format
+ * `generatorId|rootKind|fieldName`, with `rootKind` constrained to a
+ * GraphQL root operation kind (`query` / `mutation` / `subscription`).
+ */
+export const isGqlOperationGeneratorKey = (arg) => {
+    if (typeof arg !== 'string') {
+        return false;
+    }
+    const keyTokens = arg.split('|');
+    if (keyTokens.length !== 4) {
+        return false;
+    }
+    const [generatorId, rootKind, fieldName, variant] = keyTokens;
+    if (typeof generatorId !== 'string' || !generatorId.length) {
+        return false;
+    }
+    if (typeof rootKind !== 'string' || !isGqlRootKind(rootKind)) {
+        return false;
+    }
+    if (typeof fieldName !== 'string' || !fieldName.length) {
+        return false;
+    }
+    if (typeof variant !== 'string' || !variant.length) {
+        return false;
+    }
     return true;
 };
 /**
@@ -235,7 +341,7 @@ export const isOperationGeneratorKey = (arg) => {
  *
  * @example
  * ```typescript
- * const key = 'zod-schemas|User';
+ * const key = 'zod-schemas|User|main';
  *
  * if (isModelGeneratorKey(key)) {
  *   // key is now typed as ModelGeneratorKey
@@ -243,6 +349,7 @@ export const isOperationGeneratorKey = (arg) => {
  *   console.log(obj.type);        // 'model'
  *   console.log(obj.generatorId); // 'zod-schemas'
  *   console.log(obj.refName);     // 'User'
+ *   console.log(obj.variant);     // 'main'
  * }
  * ```
  */
@@ -251,16 +358,19 @@ export const isModelGeneratorKey = (arg) => {
         return false;
     }
     const keyTokens = arg.split('|');
-    if (keyTokens.length !== 2) {
+    if (keyTokens.length !== 3) {
         return false;
     }
-    const [generatorId, refName] = keyTokens;
+    const [generatorId, refName, variant] = keyTokens;
     if (typeof generatorId !== 'string' || !generatorId.length) {
         return false;
     }
     if (typeof refName !== 'string' || !refName.length) {
         return false;
     }
+    if (typeof variant !== 'string' || !variant.length) {
+        return false;
+    }
     return true;
 };
 /**
@@ -303,7 +413,7 @@ export const isGeneratorOnlyKey = (arg) => {
  *
  * @example
  * ```typescript
- * const opKey = toOperationGeneratorKey({
+ * const opKey = toOasOperationGeneratorKey({
  *   generatorId: 'api-client',
  *   path: '/users',
  *   method: 'get'
@@ -312,7 +422,8 @@ export const isGeneratorOnlyKey = (arg) => {
  *
  * const modelKey = toModelGeneratorKey({
  *   generatorId: 'typescript-types',
- *   refName: 'User'
+ *   refName: 'User',
+ *   variant: 'main'
  * });
  * console.log(toGeneratorId(modelKey)); // 'typescript-types'
  *
@@ -323,7 +434,13 @@ export const isGeneratorOnlyKey = (arg) => {
  * ```
  */
 export const toGeneratorId = (generatorKey) => {
-    if (isOperationGeneratorKey(generatorKey)) {
+    if (isOasOperationGeneratorKey(generatorKey)) {
+        return generatorKey.split('|')[0];
+    }
+    if (isWebhookGeneratorKey(generatorKey)) {
+        return generatorKey.split('|')[0];
+    }
+    if (isGqlOperationGeneratorKey(generatorKey)) {
         return generatorKey.split('|')[0];
     }
     if (isModelGeneratorKey(generatorKey)) {
@@ -343,10 +460,10 @@ export const toGeneratorId = (generatorKey) => {
  *
  * @example Operation key parsing
  * ```typescript
- * const opKey = 'api-client|/users/{id}|get' as OperationGeneratorKey;
+ * const opKey = 'api-client|/users/{id}|get' as OasOperationGeneratorKey;
  * const parsed = fromGeneratorKey(opKey);
  *
- * if (parsed.type === 'operation') {
+ * if (parsed.type === 'oasOperation') {
  *   console.log(parsed.generatorId); // 'api-client'
  *   console.log(parsed.path);        // '/users/{id}'
  *   console.log(parsed.method);      // 'get'
@@ -355,12 +472,13 @@ export const toGeneratorId = (generatorKey) => {
  *
  * @example Model key parsing
  * ```typescript
- * const modelKey = 'zod-schemas|User' as ModelGeneratorKey;
+ * const modelKey = 'zod-schemas|User|main' as ModelGeneratorKey;
  * const parsed = fromGeneratorKey(modelKey);
  *
  * if (parsed.type === 'model') {
  *   console.log(parsed.generatorId); // 'zod-schemas'
  *   console.log(parsed.refName);     // 'User'
+ *   console.log(parsed.variant);     // 'main'
  * }
  * ```
  *
@@ -375,13 +493,27 @@ export const toGeneratorId = (generatorKey) => {
  * ```
  */
 export const fromGeneratorKey = (generatorKey) => {
-    if (isOperationGeneratorKey(generatorKey)) {
-        const [generatorId, path, method] = generatorKey.split('|');
-        return { type: 'operation', generatorId, path, method: method };
+    if (isOasOperationGeneratorKey(generatorKey)) {
+        const [generatorId, path, method, variant] = generatorKey.split('|');
+        return { type: 'oasOperation', generatorId, path, method: method, variant };
+    }
+    if (isWebhookGeneratorKey(generatorKey)) {
+        const [generatorId, _webhook, name, method, variant] = generatorKey.split('|');
+        return { type: 'webhook', generatorId, name, method: method, variant };
+    }
+    if (isGqlOperationGeneratorKey(generatorKey)) {
+        const [generatorId, rootKind, fieldName, variant] = generatorKey.split('|');
+        return {
+            type: 'gqlOperation',
+            generatorId,
+            rootKind: rootKind,
+            fieldName,
+            variant
+        };
     }
     if (isModelGeneratorKey(generatorKey)) {
-        const [generatorId, refName] = generatorKey.split('|');
-        return { type: 'model', generatorId, refName };
+        const [generatorId, refName, variant] = generatorKey.split('|');
+        return { type: 'model', generatorId, refName, variant };
     }
     return { type: 'generator-only', generatorId: generatorKey };
 };

package/esm/dsl/IdentifierBase.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Constructor arguments for {@link IdentifierBase}.
+ */
+export type IdentifierBaseArgs = {
+    /** The identifier name */
+    name: string;
+    /** Optional type annotation, opaque to the engine (lang-interpreted) */
+    typeName?: string;
+    /** Whether the identifier is exported. Defaults to `true`. */
+    exported?: boolean;
+};
+/**
+ * The language-neutral coordination surface of a named entity in generated
+ * code — the minimal data the engine reads.
+ *
+ * `IdentifierBase` is engine machinery: it rides `ContentSettings`, the
+ * `(name, exportPath)` cross-generator cache key, and `DefinitionBase`. The
+ * engine reads ONLY `.name` (the cache-key source); `typeName` and
+ * `exported` are language-neutral facts it threads but never interprets.
+ * Crucially it carries NO `kind` — the per-language declaration vocabulary
+ * lives, typed, on the language subclasses.
+ *
+ * It completes the neutral `*Base` family
+ * (`CodeFileBase` / `DefinitionBase` / `ImportBase`): the concrete,
+ * kind-carrying subclasses (`TsIdentifier`, `KtIdentifier`) live in the
+ * `@skmtc/lang-*` packages and **extend** this base. Construction goes
+ * through a language package's factories (`createVariable` / `createType`
+ * for TypeScript; `createDataClass` / `createEnumClass` / … for Kotlin) or
+ * the engine's assembly seam `lang.toIdentifier({ name, ...identifierType })`.
+ * The engine holds the result as `IdentifierBase`; the language's `kind` is
+ * read only by the language renderers, which narrow via an `instanceof`
+ * guard (`isTsIdentifier` / `isKtIdentifier`).
+ */
+export declare class IdentifierBase {
+    /** The identifier name — the only field the engine reads. */
+    name: string;
+    /** Optional type annotation, opaque to the engine (lang-interpreted). */
+    typeName?: string;
+    /**
+     * Whether this identifier is exported.
+     *
+     * A language-neutral fact the engine never interprets — each language's
+     * renderer decides what it means syntactically: TypeScript emits/omits
+     * `export`, Go capitalizes the name (visibility via casing), others may
+     * ignore it. Defaults to `true`.
+     */
+    exported: boolean;
+    constructor({ name, typeName, exported }: IdentifierBaseArgs);
+    /**
+     * Returns the identifier name — the most common usage when the
+     * identifier is interpolated into generated code.
+     */
+    toString(): string;
+}
+//# sourceMappingURL=IdentifierBase.d.ts.map

package/esm/dsl/IdentifierBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IdentifierBase.d.ts","sourceRoot":"","sources":["../../src/dsl/IdentifierBase.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,cAAc;IACzB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IAEZ,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;;;;;OAOG;IACH,QAAQ,EAAE,OAAO,CAAA;gBAEL,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,kBAAkB;IAM5D;;;OAGG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/esm/dsl/IdentifierBase.js

@@ -0,0 +1,64 @@
+/**
+ * The language-neutral coordination surface of a named entity in generated
+ * code — the minimal data the engine reads.
+ *
+ * `IdentifierBase` is engine machinery: it rides `ContentSettings`, the
+ * `(name, exportPath)` cross-generator cache key, and `DefinitionBase`. The
+ * engine reads ONLY `.name` (the cache-key source); `typeName` and
+ * `exported` are language-neutral facts it threads but never interprets.
+ * Crucially it carries NO `kind` — the per-language declaration vocabulary
+ * lives, typed, on the language subclasses.
+ *
+ * It completes the neutral `*Base` family
+ * (`CodeFileBase` / `DefinitionBase` / `ImportBase`): the concrete,
+ * kind-carrying subclasses (`TsIdentifier`, `KtIdentifier`) live in the
+ * `@skmtc/lang-*` packages and **extend** this base. Construction goes
+ * through a language package's factories (`createVariable` / `createType`
+ * for TypeScript; `createDataClass` / `createEnumClass` / … for Kotlin) or
+ * the engine's assembly seam `lang.toIdentifier({ name, ...identifierType })`.
+ * The engine holds the result as `IdentifierBase`; the language's `kind` is
+ * read only by the language renderers, which narrow via an `instanceof`
+ * guard (`isTsIdentifier` / `isKtIdentifier`).
+ */
+export class IdentifierBase {
+    constructor({ name, typeName, exported }) {
+        /** The identifier name — the only field the engine reads. */
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Optional type annotation, opaque to the engine (lang-interpreted). */
+        Object.defineProperty(this, "typeName", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * Whether this identifier is exported.
+         *
+         * A language-neutral fact the engine never interprets — each language's
+         * renderer decides what it means syntactically: TypeScript emits/omits
+         * `export`, Go capitalizes the name (visibility via casing), others may
+         * ignore it. Defaults to `true`.
+         */
+        Object.defineProperty(this, "exported", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = name;
+        this.typeName = typeName;
+        this.exported = exported ?? true;
+    }
+    /**
+     * Returns the identifier name — the most common usage when the
+     * identifier is interpolated into generated code.
+     */
+    toString() {
+        return this.name;
+    }
+}

package/esm/dsl/IdentifierType.d.ts

@@ -0,0 +1,31 @@
+import type { Lang, LangKind } from './Lang.js';
+/**
+ * The non-`name` parts of an identifier — everything a projection's
+ * `toIdentifierType` derives from the schema (context-aware), bundled so
+ * the engine can assemble the full identifier with
+ * `lang.toIdentifier({ name, ...identifierType })`.
+ *
+ * Generic over the projection's {@link Lang}: the `kind` is drawn from that
+ * language's declaration vocabulary, recovered via {@link LangKind} from the
+ * typed `kind` on the {@link import('@/dsl/IdentifierBase.ts').IdentifierBase}
+ * subclass the lang produces (`KtEntityKind` for `KtLang`, `TsEntityKind` for
+ * the TypeScript `Lang`, …). A bare `Lang` falls back to the loose
+ * `kind: string` — the opaque-kind boundary the engine never interprets.
+ *
+ * This is what lets a language's projection-base veneer parameterize core's
+ * config (`ModelProjectionBaseConfig<E, KtLang>`) instead of recasting
+ * `toIdentifierType`'s return: the tightening rides the `L` type argument.
+ *
+ * Pairs with `toIdentifierName(args) -> string` (the pure, cache-key
+ * source): the engine assembles
+ * `lang.toIdentifier({ name: P.toIdentifierName(args), ...P.toIdentifierType(coordinate, context) })`.
+ */
+export type IdentifierType<L extends Lang = Lang> = {
+    /** Per-language declaration kind — `LangKind<L>`, opaque to the engine. */
+    kind: LangKind<L>;
+    /** Optional type annotation, opaque to the engine (lang-interpreted). */
+    typeName?: string;
+    /** Whether the identifier is exported. Defaults to `true`. */
+    exported?: boolean;
+};
+//# sourceMappingURL=IdentifierType.d.ts.map

package/esm/dsl/IdentifierType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IdentifierType.d.ts","sourceRoot":"","sources":["../../src/dsl/IdentifierType.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,IAAI,GAAG,IAAI,IAAI;IAClD,2EAA2E;IAC3E,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;IACjB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA"}

package/esm/dsl/IdentifierType.js

@@ -0,0 +1 @@
+export {};

package/esm/dsl/ImportBase.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The language-neutral contract for a registered import.
+ *
+ * A `@skmtc/lang-*` package provides a concrete subclass (`TsImport`,
+ * `GoImport`, …) that owns the language's import shape and rendering. The
+ * engine and {@link import('@/dsl/CodeFileBase.ts').CodeFileBase} only ever
+ * see this neutral surface:
+ *
+ * - `mergeKey()` — identity for dedup AND the handle a `File` uses to
+ *   arrange its import section (typically the module / package path). Two
+ *   imports with the same key collapse via {@link merge}.
+ * - `merge(other)` — combine a same-key import into this one (e.g. union
+ *   their symbols). The subclass narrows `other` to its own type.
+ * - `toString()` — render the standalone import. A language `File` MAY
+ *   re-arrange instead (e.g. Go groups every package into one
+ *   `import ( … )` block keyed by `mergeKey()`), so `toString()` is the
+ *   per-import render, not the whole section.
+ *
+ * The split is deliberate: the *merge* of imports is language-neutral (it
+ * lives on `CodeFileBase`); the *arrangement* of the import section is
+ * language-specific (it lives in the concrete `File.toString()`).
+ */
+export declare abstract class ImportBase {
+    /**
+     * Identity for dedup and arrangement — typically the module or package
+     * path. Imports sharing a `mergeKey()` are merged via {@link merge}; a
+     * `File` may also group or sort its imports by this key.
+     */
+    abstract mergeKey(): string;
+    /**
+     * Combine another import that shares this `mergeKey()` into a single
+     * import. The concrete subclass narrows `other` to its own type (and
+     * throws if handed a foreign import — which only happens if two languages
+     * wrote to one file, a misconfiguration).
+     */
+    abstract merge(other: ImportBase): ImportBase;
+    /** Render the standalone import. The `File` may re-arrange via `mergeKey`. */
+    abstract toString(): string;
+}
+//# sourceMappingURL=ImportBase.d.ts.map

package/esm/dsl/ImportBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImportBase.d.ts","sourceRoot":"","sources":["../../src/dsl/ImportBase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8BAAsB,UAAU;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,IAAI,MAAM;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU;IAE7C,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,IAAI,MAAM;CAC5B"}