@skmtc/core 0.0.984 → 0.16.1

package/script/dsl/GeneratorKeys.js

@@ -1,4 +1,6 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromGeneratorKey = exports.toGeneratorId = exports.isGeneratorOnlyKey = exports.isModelGeneratorKey = exports.isGqlOperationGeneratorKey = exports.isWebhookGeneratorKey = exports.isOasOperationGeneratorKey = exports.isGeneratorKey = exports.toGeneratorOnlyKey = exports.toModelGeneratorKey = exports.toGqlOperationGeneratorKey = exports.toWebhookGeneratorKey = exports.toOasOperationGeneratorKey = void 0;
 /**
  * @fileoverview Generator Key System for SKMTC Core
  *
@@ -18,66 +20,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
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.fromGeneratorKey = exports.toGeneratorId = exports.isGeneratorOnlyKey = exports.isModelGeneratorKey = exports.isOperationGeneratorKey = exports.isGeneratorKey = exports.toGeneratorOnlyKey = exports.toModelGeneratorKey = exports.toOperationGeneratorKey = void 0;
+require("../_dnt.polyfills.js");
 const Method_js_1 = require("../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'
@@ -93,24 +98,53 @@ const Method_js_1 = require("../types/Method.js");
  *   // ... other operation details
  * });
  *
- * const key = toOperationGeneratorKey({
+ * const key = toOasOperationGeneratorKey({
  *   generatorId: 'rest-client',
  *   operation
  * });
  * // Result: 'rest-client|/posts|post' (branded)
  * ```
  */
-const toOperationGeneratorKey = ({ generatorId, ...rest }) => {
+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;
+};
+exports.toOasOperationGeneratorKey = toOasOperationGeneratorKey;
+/**
+ * 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.
+ */
+const toWebhookGeneratorKey = ({ generatorId, variant, ...rest }) => {
+    const { name, method } = 'webhook' in rest ? rest.webhook : rest;
+    const nakedKey = `${generatorId}|webhook|${name}|${method}|${variant}`;
     return nakedKey;
 };
-exports.toOperationGeneratorKey = toOperationGeneratorKey;
+exports.toWebhookGeneratorKey = toWebhookGeneratorKey;
 /**
- * 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`.
+ */
+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;
+};
+exports.toGqlOperationGeneratorKey = toGqlOperationGeneratorKey;
+/**
+ * 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
@@ -119,19 +153,21 @@ exports.toOperationGeneratorKey = toOperationGeneratorKey;
  * ```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)
  * ```
  */
-const toModelGeneratorKey = ({ generatorId, refName }) => {
-    const nakedKey = `${generatorId}|${refName}`;
+const toModelGeneratorKey = ({ generatorId, refName, variant }) => {
+    const nakedKey = `${generatorId}|${refName}|${variant}`;
     return nakedKey;
 };
 exports.toModelGeneratorKey = toModelGeneratorKey;
@@ -184,42 +220,46 @@ exports.toGeneratorOnlyKey = toGeneratorOnlyKey;
  * ```
  */
 const isGeneratorKey = (arg) => {
-    return (0, exports.isModelGeneratorKey)(arg) || (0, exports.isOperationGeneratorKey)(arg) || (0, exports.isGeneratorOnlyKey)(arg);
+    return ((0, exports.isModelGeneratorKey)(arg) ||
+        (0, exports.isOasOperationGeneratorKey)(arg) ||
+        (0, exports.isWebhookGeneratorKey)(arg) ||
+        (0, exports.isGqlOperationGeneratorKey)(arg) ||
+        (0, exports.isGeneratorOnlyKey)(arg));
 };
 exports.isGeneratorKey = isGeneratorKey;
 /**
- * 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'
  * }
  * ```
  */
-const isOperationGeneratorKey = (arg) => {
+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;
     }
@@ -229,9 +269,79 @@ const isOperationGeneratorKey = (arg) => {
     if (!(0, Method_js_1.isMethod)(method)) {
         return false;
     }
+    if (typeof variant !== 'string' || !variant.length) {
+        return false;
+    }
     return true;
 };
-exports.isOperationGeneratorKey = isOperationGeneratorKey;
+exports.isOasOperationGeneratorKey = isOasOperationGeneratorKey;
+/**
+ * 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.
+ */
+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 (!(0, Method_js_1.isMethod)(method)) {
+        return false;
+    }
+    if (typeof variant !== 'string' || !variant.length) {
+        return false;
+    }
+    return true;
+};
+exports.isWebhookGeneratorKey = isWebhookGeneratorKey;
+/**
+ * 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`).
+ */
+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;
+};
+exports.isGqlOperationGeneratorKey = isGqlOperationGeneratorKey;
 /**
  * Type guard to check if a value is a valid ModelGeneratorKey.
  *
@@ -243,7 +353,7 @@ exports.isOperationGeneratorKey = isOperationGeneratorKey;
  *
  * @example
  * ```typescript
- * const key = 'zod-schemas|User';
+ * const key = 'zod-schemas|User|main';
  *
  * if (isModelGeneratorKey(key)) {
  *   // key is now typed as ModelGeneratorKey
@@ -251,6 +361,7 @@ exports.isOperationGeneratorKey = isOperationGeneratorKey;
  *   console.log(obj.type);        // 'model'
  *   console.log(obj.generatorId); // 'zod-schemas'
  *   console.log(obj.refName);     // 'User'
+ *   console.log(obj.variant);     // 'main'
  * }
  * ```
  */
@@ -259,16 +370,19 @@ 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;
 };
 exports.isModelGeneratorKey = isModelGeneratorKey;
@@ -313,7 +427,7 @@ exports.isGeneratorOnlyKey = isGeneratorOnlyKey;
  *
  * @example
  * ```typescript
- * const opKey = toOperationGeneratorKey({
+ * const opKey = toOasOperationGeneratorKey({
  *   generatorId: 'api-client',
  *   path: '/users',
  *   method: 'get'
@@ -322,7 +436,8 @@ exports.isGeneratorOnlyKey = isGeneratorOnlyKey;
  *
  * const modelKey = toModelGeneratorKey({
  *   generatorId: 'typescript-types',
- *   refName: 'User'
+ *   refName: 'User',
+ *   variant: 'main'
  * });
  * console.log(toGeneratorId(modelKey)); // 'typescript-types'
  *
@@ -333,7 +448,13 @@ exports.isGeneratorOnlyKey = isGeneratorOnlyKey;
  * ```
  */
 const toGeneratorId = (generatorKey) => {
-    if ((0, exports.isOperationGeneratorKey)(generatorKey)) {
+    if ((0, exports.isOasOperationGeneratorKey)(generatorKey)) {
+        return generatorKey.split('|')[0];
+    }
+    if ((0, exports.isWebhookGeneratorKey)(generatorKey)) {
+        return generatorKey.split('|')[0];
+    }
+    if ((0, exports.isGqlOperationGeneratorKey)(generatorKey)) {
         return generatorKey.split('|')[0];
     }
     if ((0, exports.isModelGeneratorKey)(generatorKey)) {
@@ -354,10 +475,10 @@ exports.toGeneratorId = toGeneratorId;
  *
  * @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'
@@ -366,12 +487,13 @@ exports.toGeneratorId = toGeneratorId;
  *
  * @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'
  * }
  * ```
  *
@@ -386,13 +508,27 @@ exports.toGeneratorId = toGeneratorId;
  * ```
  */
 const fromGeneratorKey = (generatorKey) => {
-    if ((0, exports.isOperationGeneratorKey)(generatorKey)) {
-        const [generatorId, path, method] = generatorKey.split('|');
-        return { type: 'operation', generatorId, path, method: method };
+    if ((0, exports.isOasOperationGeneratorKey)(generatorKey)) {
+        const [generatorId, path, method, variant] = generatorKey.split('|');
+        return { type: 'oasOperation', generatorId, path, method: method, variant };
+    }
+    if ((0, exports.isWebhookGeneratorKey)(generatorKey)) {
+        const [generatorId, _webhook, name, method, variant] = generatorKey.split('|');
+        return { type: 'webhook', generatorId, name, method: method, variant };
+    }
+    if ((0, exports.isGqlOperationGeneratorKey)(generatorKey)) {
+        const [generatorId, rootKind, fieldName, variant] = generatorKey.split('|');
+        return {
+            type: 'gqlOperation',
+            generatorId,
+            rootKind: rootKind,
+            fieldName,
+            variant
+        };
     }
     if ((0, exports.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/script/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/script/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/script/dsl/IdentifierBase.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentifierBase = void 0;
+/**
+ * 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`).
+ */
+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;
+    }
+}
+exports.IdentifierBase = IdentifierBase;

package/script/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/script/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/script/dsl/IdentifierType.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });