semantic-primitives 0.1.0

package/dist/primitives/symbol/symbol.d.ts

@@ -0,0 +1,176 @@
+/**
+ * SemanticSymbol - LLM-enhanced symbol type with semantic understanding
+ *
+ * Extends the native JavaScript Symbol with semantic operations including:
+ * - Semantic equivalence comparison
+ * - Name suggestion based on conventions
+ * - Category classification
+ * - Validation against best practices
+ * - Purpose description
+ * - Appropriateness assessment
+ *
+ * Implements shared interfaces:
+ * - Semantic<symbol> - Base semantic wrapper
+ * - Comparable<SemanticSymbol | symbol> - Semantic equality comparison
+ */
+import type { LLMConfig, Message } from '../../llm/types.ts';
+import type { SemanticEqualsResultWithReason, ValidateResultWithWarnings, AppropriateResult, Suggestion } from '../../shared/types.ts';
+import type { Semantic, Comparable } from '../../shared/interfaces.ts';
+export type { SemanticEqualsResultWithReason, ValidateResultWithWarnings, AppropriateResult, Suggestion, } from '../../shared/types.ts';
+/** LLM client interface for dependency injection */
+export interface LLMClientInterface {
+    chat(options: {
+        messages: Message[];
+        systemPrompt?: string;
+    } & LLMConfig): Promise<{
+        content: string;
+    }>;
+}
+/** Result type for classification without confidence */
+export interface SymbolClassifyResult {
+    category: string;
+    subcategory?: string;
+}
+/**
+ * SemanticSymbol class
+ * Wraps a Symbol with LLM-powered semantic operations
+ *
+ * Implements:
+ * - Semantic<symbol> - valueOf() returns the symbol
+ * - Comparable<SemanticSymbol | symbol> - semanticallyEquals() for comparison
+ */
+export declare class SemanticSymbol implements Semantic<symbol>, Comparable<SemanticSymbol | symbol> {
+    private readonly _symbol;
+    private readonly _description;
+    private readonly _llmClient;
+    private readonly _llmConfig?;
+    /**
+     * Private constructor - use static factory methods to create instances
+     */
+    private constructor();
+    /**
+     * Create a SemanticSymbol with a semantically meaningful description.
+     *
+     * @param description - Human-readable description of the symbol's purpose
+     * @param llmClient - Optional LLM client for dependency injection
+     * @param llmConfig - Optional LLM configuration
+     * @returns SemanticSymbol instance
+     *
+     * @example
+     * SemanticSymbol.create("userAuthToken")
+     * SemanticSymbol.create("cacheInvalidationKey")
+     */
+    static create(description: string, llmClient?: LLMClientInterface, llmConfig?: LLMConfig): SemanticSymbol;
+    /**
+     * Create or retrieve a global symbol with semantic validation.
+     * Uses the global symbol registry to ensure the same key always returns the same SemanticSymbol.
+     *
+     * @param key - Registry key for the symbol
+     * @param llmClient - Optional LLM client for dependency injection
+     * @param llmConfig - Optional LLM configuration
+     * @returns SemanticSymbol from global registry
+     *
+     * @example
+     * SemanticSymbol.for("app.config.database")
+     * SemanticSymbol.for("plugin.lifecycle.init")
+     */
+    static for(key: string, llmClient?: LLMClientInterface, llmConfig?: LLMConfig): SemanticSymbol;
+    /**
+     * Wrap an existing symbol in a SemanticSymbol.
+     *
+     * @param symbol - The native symbol to wrap
+     * @param llmClient - Optional LLM client for dependency injection
+     * @param llmConfig - Optional LLM configuration
+     * @returns SemanticSymbol instance
+     */
+    static from(symbol: symbol, llmClient?: LLMClientInterface, llmConfig?: LLMConfig): SemanticSymbol;
+    /**
+     * Check if two symbols serve the same semantic purpose.
+     * Even unique symbols can be semantically equivalent in purpose.
+     *
+     * @param other - Another symbol to compare
+     * @returns Equivalence result with confidence and note
+     *
+     * @example
+     * SemanticSymbol.create("userId").semanticallyEquals(SemanticSymbol.create("user_id"))
+     * // { equivalent: true, confidence: 0.95, note: "Same concept, different naming convention" }
+     */
+    semanticallyEquals(other: SemanticSymbol | symbol): Promise<SemanticEqualsResultWithReason>;
+    /**
+     * Suggest a better description for the symbol based on conventions.
+     *
+     * @returns Suggestion with explanation
+     *
+     * @example
+     * SemanticSymbol.create("x").suggestBetterName()
+     * // { suggestion: null, reason: "Cannot suggest without more context" }
+     *
+     * SemanticSymbol.create("usrid").suggestBetterName()
+     * // { suggestion: "userId", reason: "Use camelCase and avoid abbreviations" }
+     */
+    suggestBetterName(): Promise<Suggestion>;
+    /**
+     * Classify the symbol into a category based on its description.
+     *
+     * @returns Category classification
+     *
+     * @example
+     * SemanticSymbol.create("onUserLogin").classify()
+     * // { category: "event", subcategory: "lifecycle" }
+     *
+     * SemanticSymbol.create("API_SECRET_KEY").classify()
+     * // { category: "configuration", subcategory: "secrets" }
+     */
+    classify(): Promise<SymbolClassifyResult>;
+    /**
+     * Validate the symbol description follows best practices.
+     *
+     * @param conventions - Optional custom conventions to check against
+     * @returns Validation result with warnings
+     *
+     * @example
+     * SemanticSymbol.create("_private_internal").validate()
+     * // { valid: true, warnings: ["Underscore prefix suggests private; consider using # for true privacy"] }
+     */
+    validate(conventions?: string[]): Promise<ValidateResultWithWarnings>;
+    /**
+     * Get the semantic purpose/intent of this symbol.
+     *
+     * @returns Description of the symbol's purpose
+     *
+     * @example
+     * SemanticSymbol.create("cacheKey").describePurpose()
+     * // "Unique identifier for cache entries"
+     */
+    describePurpose(): Promise<string>;
+    /**
+     * Check if this symbol is appropriate for a given use case.
+     *
+     * @param useCase - The intended use case
+     * @returns Appropriateness assessment
+     *
+     * @example
+     * SemanticSymbol.create("tempId").isAppropriateFor("database primary key")
+     * // { appropriate: false, reason: "Temporary identifiers should not be used as permanent keys" }
+     */
+    isAppropriateFor(useCase: string): Promise<AppropriateResult>;
+    /**
+     * Get the underlying Symbol value.
+     * @returns The native Symbol
+     */
+    valueOf(): symbol;
+    /**
+     * Get the symbol's description.
+     * @returns The description string or undefined
+     */
+    description(): string | undefined;
+    /**
+     * Convert to string representation
+     */
+    toString(): string;
+    /**
+     * Convert to JSON - symbols cannot be serialized, returns description
+     */
+    toJSON(): string | undefined;
+}
+//# sourceMappingURL=symbol.d.ts.map

package/dist/primitives/symbol/symbol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol.d.ts","sourceRoot":"","sources":["../../../src/primitives/symbol/symbol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EACV,8BAA8B,EAC9B,0BAA0B,EAC1B,iBAAiB,EACjB,UAAU,EACX,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAiBvE,YAAY,EACV,8BAA8B,EAC9B,0BAA0B,EAC1B,iBAAiB,EACjB,UAAU,GACX,MAAM,uBAAuB,CAAC;AAE/B,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzG;AAED,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAKD;;;;;;;GAOG;AACH,qBAAa,cAAe,YAAW,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,cAAc,GAAG,MAAM,CAAC;IAC1F,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAY;IAExC;;OAEG;IACH,OAAO;IAgBP;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,MAAM,CACX,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,kBAAkB,EAC9B,SAAS,CAAC,EAAE,SAAS,GACpB,cAAc;IAIjB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,GAAG,CACR,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,kBAAkB,EAC9B,SAAS,CAAC,EAAE,SAAS,GACpB,cAAc;IAcjB;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,CACT,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,kBAAkB,EAC9B,SAAS,CAAC,EAAE,SAAS,GACpB,cAAc;IAIjB;;;;;;;;;;OAUG;IACG,kBAAkB,CACtB,KAAK,EAAE,cAAc,GAAG,MAAM,GAC7B,OAAO,CAAC,8BAA8B,CAAC;IAmC1C;;;;;;;;;;;OAWG;IACG,iBAAiB,IAAI,OAAO,CAAC,UAAU,CAAC;IA+B9C;;;;;;;;;;;OAWG;IACG,QAAQ,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAuB/C;;;;;;;;;OASG;IACG,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAiC3E;;;;;;;;OAQG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC;IAqBxC;;;;;;;;;OASG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAuBnE;;;OAGG;IACH,OAAO,IAAI,MAAM;IAIjB;;;OAGG;IACH,WAAW,IAAI,MAAM,GAAG,SAAS;IAIjC;;OAEG;IACH,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,MAAM,IAAI,MAAM,GAAG,SAAS;CAG7B"}

package/dist/primitives/symbol/symbol.prompts.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Prompts for SemanticSymbol LLM operations
+ * These prompts are used for various semantic symbol operations that require LLM understanding
+ */
+/**
+ * System prompt for semantic equality comparison of symbols
+ */
+export declare const SEMANTIC_EQUALS_SYSTEM = "You are a symbol naming expert. Your task is to determine if two symbol descriptions serve the same semantic purpose.\n\nConsider:\n- Naming conventions (camelCase, snake_case, SCREAMING_CASE)\n- Common abbreviations and their expansions\n- Synonyms and related concepts\n- The underlying intent, not just the literal text\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for semantic equality
+ */
+export declare function semanticEqualsPrompt(desc1: string, desc2: string): string;
+/**
+ * System prompt for suggesting better names
+ */
+export declare const SUGGEST_NAME_SYSTEM = "You are a code naming expert. Your task is to suggest better names for identifiers based on best practices.\n\nBest practices:\n- Use descriptive, meaningful names\n- Follow camelCase for most identifiers\n- Avoid single letters except for well-known conventions (i, j for loops)\n- Expand abbreviations when clarity is improved\n- Keep names concise but clear\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for suggesting better names
+ */
+export declare function suggestBetterNamePrompt(description: string): string;
+/**
+ * System prompt for classifying symbols
+ */
+export declare const CLASSIFY_SYSTEM = "You are a code analysis expert. Your task is to classify symbol descriptions into categories.\n\nCategories:\n- event: Event handlers, listeners, callbacks (e.g., onClick, onUserLogin)\n- configuration: Config keys, settings, options (e.g., API_KEY, maxRetries)\n- lifecycle: Initialization, cleanup, state transitions (e.g., init, destroy, mount)\n- identifier: IDs, keys, references (e.g., userId, cacheKey)\n- action: Methods, commands, operations (e.g., submit, validate, process)\n- data: Data structures, storage (e.g., userData, itemList)\n- constant: Unchanging values (e.g., MAX_SIZE, DEFAULT_TIMEOUT)\n- internal: Private/internal markers (e.g., _private, __internal)\n- metadata: Descriptive information (e.g., version, timestamp)\n- unknown: Cannot be determined\n\nSubcategories provide more specific classification within each category.\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for classification
+ */
+export declare function classifyPrompt(description: string): string;
+/**
+ * System prompt for validation
+ */
+export declare const VALIDATE_SYSTEM = "You are a code review expert. Your task is to validate symbol descriptions against naming conventions and best practices.\n\nCheck for:\n- Clarity and descriptiveness\n- Consistent naming convention (camelCase, snake_case, etc.)\n- Appropriate length (not too short, not too long)\n- Avoidance of reserved words or problematic names\n- Proper use of prefixes/suffixes\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for validation
+ */
+export declare function validatePrompt(description: string, conventions?: string[]): string;
+/**
+ * System prompt for describing purpose
+ */
+export declare const DESCRIBE_PURPOSE_SYSTEM = "You are a documentation expert. Your task is to describe the likely purpose of a symbol based on its name.\n\nConsider:\n- Common naming patterns in programming\n- Domain-specific terminology\n- Prefixes and suffixes that indicate purpose\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for describing purpose
+ */
+export declare function describePurposePrompt(description: string): string;
+/**
+ * System prompt for appropriateness check
+ */
+export declare const IS_APPROPRIATE_SYSTEM = "You are a software design expert. Your task is to assess if a symbol is appropriate for a given use case.\n\nConsider:\n- Semantic fit between the name and use case\n- Potential confusion or misuse\n- Naming conventions for the specific use case\n- Longevity and maintainability concerns\n\nAlways respond with valid JSON only.";
+/**
+ * User prompt template for appropriateness check
+ */
+export declare function isAppropriateForPrompt(description: string, useCase: string): string;
+//# sourceMappingURL=symbol.prompts.d.ts.map

package/dist/primitives/symbol/symbol.prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol.prompts.d.ts","sourceRoot":"","sources":["../../../src/primitives/symbol/symbol.prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,sBAAsB,+WAQE,CAAC;AAEtC;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAUzE;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,qZASK,CAAC;AAEtC;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAUnE;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,+3BAgBS,CAAC;AAEtC;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAO1D;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,4ZASS,CAAC;AAEtC;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAWlF;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,2RAOC,CAAC;AAEtC;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CASjE;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,4UAQG,CAAC;AAEtC;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQnF"}

package/dist/primitives/undefined/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * SemanticUndefined exports
+ */
+export { SemanticUndefined, type UndefinedType, type UndefinedClassifyResult, type SuggestInitializationResult, type TypeHint, type AcceptableResult, type CompareToNullResult, type SemanticEqualsResult, type InferReasonResult, } from './undefined.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/primitives/undefined/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/primitives/undefined/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,iBAAiB,EACjB,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,gBAAgB,CAAC"}

package/dist/primitives/undefined/prompts.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Prompts for SemanticUndefined LLM operations
+ * These prompts are used to reason about undefined values and their semantic meaning
+ */
+/**
+ * System prompt for undefined interpretation tasks
+ */
+export declare const UNDEFINED_SYSTEM_PROMPT = "You are a semantic undefined value interpreter. Your task is to analyze and reason about undefined values, their meaning, and appropriate handling in JavaScript/TypeScript contexts.\n\nYou must respond with valid JSON only, no additional text or explanation.\n\nKey concepts:\n- \"not-initialized\": A variable/property that has been declared but not assigned a value\n- \"optional-unset\": An optional parameter/property that was not provided\n- \"property-missing\": Accessing a property that doesn't exist on an object\n- \"void-return\": A function that doesn't explicitly return a value\n- \"unknown\": The reason for undefined is unclear or indeterminate\n\nGuidelines:\n- Consider property/variable names when inferring reasons\n- Analyze context to determine if undefined is intentional or a potential bug\n- Provide confidence scores from 0.0 to 1.0 based on clarity\n- Suggest appropriate initializations only when safe (never for sensitive data)\n- Distinguish between undefined (uninitialized) and null (intentional absence)";
+/**
+ * Prompt template for comparing two undefined contexts for semantic equivalence
+ */
+export declare function createSemanticallyEqualsPrompt(context1: string, context2: string): string;
+/**
+ * Prompt template for inferring the reason a property/value is undefined
+ */
+export declare function createInferReasonPrompt(propertyPath: string, context?: unknown): string;
+/**
+ * Prompt template for suggesting an appropriate initialization value
+ */
+export declare function createSuggestInitializationPrompt(propertyName: string, typeHint?: {
+    type: string;
+    schema?: unknown;
+}): string;
+/**
+ * Prompt template for checking if undefined is acceptable for a context
+ */
+export declare function createIsAcceptablePrompt(context: string, details?: Record<string, unknown>): string;
+/**
+ * Prompt template for comparing null vs undefined appropriateness
+ */
+export declare function createCompareToNullPrompt(context: string): string;
+/**
+ * Prompt template for generating a human-readable explanation
+ */
+export declare function createExplainPrompt(propertyPath: string, context?: string): string;
+/**
+ * Prompt template for classifying the type of undefined
+ */
+export declare function createClassifyPrompt(context: string): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/primitives/undefined/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/primitives/undefined/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,uBAAuB,ihCAgB2C,CAAC;AAEhF;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,MAAM,CAgBR;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,OAAO,GAChB,MAAM,CAuBR;AAED;;GAEG;AACH,wBAAgB,iCAAiC,CAC/C,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5C,MAAM,CA2BR;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,MAAM,CAwBR;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAkBjE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAsBR;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAmB5D"}

package/dist/primitives/undefined/undefined.d.ts

@@ -0,0 +1,216 @@
+/**
+ * SemanticUndefined
+ * An undefined type with LLM-powered semantic understanding
+ *
+ * Implements shared interfaces:
+ * - Semantic<undefined> - Base semantic wrapper
+ * - Comparable<SemanticUndefined> - Semantic equality comparison
+ * - Explainable - Human-readable explanation
+ *
+ * Note: Does not implement SemanticAbsence<undefined> because undefined
+ * has different classification types than null (not-initialized, optional-unset,
+ * property-missing, void-return vs not-set, not-applicable).
+ */
+import type { LLMClient } from '../../llm/client.ts';
+import type { SemanticEqualsResult, InferReasonResult } from '../../shared/types.ts';
+import type { Semantic, Comparable, Explainable } from '../../shared/interfaces.ts';
+export type { SemanticEqualsResult, InferReasonResult, } from '../../shared/types.ts';
+/** Classification types for undefined values */
+export type UndefinedType = 'not-initialized' | 'optional-unset' | 'property-missing' | 'void-return' | 'unknown';
+/** Result of undefined classification */
+export interface UndefinedClassifyResult {
+    type: UndefinedType;
+    canBeInitialized: boolean;
+}
+/** Result of suggesting an initialization value */
+export interface SuggestInitializationResult {
+    value: unknown;
+    explanation: string;
+}
+/** Type hint for initialization suggestion */
+export interface TypeHint {
+    type: string;
+    schema?: unknown;
+}
+/** Result of checking if undefined is acceptable */
+export interface AcceptableResult {
+    acceptable: boolean;
+    reason: string;
+}
+/** Result of comparing null vs undefined */
+export interface CompareToNullResult {
+    recommendation: 'null' | 'undefined';
+    explanation: string;
+}
+/**
+ * SemanticUndefined - Undefined with LLM-powered semantic understanding
+ *
+ * Unlike plain undefined that only represents an uninitialized/missing value,
+ * SemanticUndefined can explain why a value is undefined, suggest initialization,
+ * and help reason about appropriate handling.
+ *
+ * Implements:
+ * - Semantic<undefined> - valueOf() returns undefined
+ * - Comparable<SemanticUndefined> - semanticallyEquals() for comparison
+ * - Explainable - explain() for human-readable description
+ * - SemanticAbsence<undefined> - getReason() and classify()
+ */
+export declare class SemanticUndefined implements Semantic<undefined>, Comparable<SemanticUndefined>, Explainable {
+    private readonly context;
+    private readonly client;
+    private constructor();
+    /**
+     * Create a SemanticUndefined with context about why the value is undefined.
+     *
+     * @param context - Context explaining the undefined state
+     * @param client - Optional LLM client for dependency injection
+     * @returns SemanticUndefined instance with context
+     *
+     * @example
+     * SemanticUndefined.because("property not yet initialized")
+     * SemanticUndefined.because("optional parameter not provided")
+     */
+    static because(context: string, client?: LLMClient): SemanticUndefined;
+    /**
+     * Create a SemanticUndefined without a context.
+     *
+     * @param client - Optional LLM client for dependency injection
+     * @returns SemanticUndefined instance
+     */
+    static create(client?: LLMClient): SemanticUndefined;
+    /**
+     * Check if two undefined values are semantically equivalent.
+     * Undefined values with similar contexts are considered equivalent.
+     *
+     * @param other - Another SemanticUndefined to compare
+     * @returns Equivalence result with confidence score
+     *
+     * @example
+     * await SemanticUndefined.because("not initialized").semanticallyEquals(
+     *   SemanticUndefined.because("unset")
+     * )
+     * // { equivalent: true, confidence: 0.9 }
+     */
+    semanticallyEquals(other: SemanticUndefined): Promise<SemanticEqualsResult>;
+    /**
+     * Infer why a value is undefined based on context.
+     *
+     * @param propertyPath - The property path that is undefined
+     * @param context - Surrounding context
+     * @param client - Optional LLM client for dependency injection
+     * @returns Inferred reason
+     *
+     * @example
+     * await SemanticUndefined.inferReason("user.profile.avatar", { user: { profile: {} } })
+     * // { reason: "Optional property not set", type: "optional-unset" }
+     */
+    static inferReason(propertyPath: string, context?: unknown, client?: LLMClient): Promise<InferReasonResult>;
+    /**
+     * Suggest an appropriate initialization value.
+     *
+     * @param propertyName - Name of the property
+     * @param typeHint - Optional type information
+     * @param client - Optional LLM client for dependency injection
+     * @returns Suggested initialization with explanation
+     *
+     * @example
+     * await SemanticUndefined.suggestInitialization("items", { type: "array" })
+     * // { value: [], explanation: "Arrays should be initialized empty, not undefined" }
+     *
+     * await SemanticUndefined.suggestInitialization("config", { type: "object" })
+     * // { value: {}, explanation: "Objects should be initialized empty" }
+     */
+    static suggestInitialization(propertyName: string, typeHint?: TypeHint, client?: LLMClient): Promise<SuggestInitializationResult>;
+    /**
+     * Determine if undefined is acceptable here or indicates a bug.
+     *
+     * @param context - Context about where this undefined occurred
+     * @param details - Additional details
+     * @param client - Optional LLM client for dependency injection
+     * @returns Assessment result
+     *
+     * @example
+     * await SemanticUndefined.isAcceptable("return value", { functionName: "getUserById" })
+     * // { acceptable: false, reason: "Function should return null for not found, not undefined" }
+     */
+    static isAcceptable(context: string, details?: Record<string, unknown>, client?: LLMClient): Promise<AcceptableResult>;
+    /**
+     * Check if this undefined differs semantically from null.
+     * Explains when null vs undefined should be used.
+     *
+     * @param context - Context for the comparison
+     * @param client - Optional LLM client for dependency injection
+     * @returns Explanation of which is more appropriate
+     *
+     * @example
+     * await SemanticUndefined.compareToNull("user.deletedAt")
+     * // {
+     * //   recommendation: "null",
+     * //   explanation: "Use null for intentional absence (not deleted), undefined implies uninitialized"
+     * // }
+     */
+    static compareToNull(context: string, client?: LLMClient): Promise<CompareToNullResult>;
+    /**
+     * Determine if this undefined represents a specific classification.
+     *
+     * @returns Classification of the undefined type
+     *
+     * @example
+     * // For a property that was never initialized:
+     * // { type: "not-initialized", canBeInitialized: true }
+     *
+     * // For an optional parameter not provided:
+     * // { type: "optional-unset", canBeInitialized: true }
+     */
+    classify(): Promise<UndefinedClassifyResult>;
+    /**
+     * Generate a human-readable explanation of this undefined value.
+     *
+     * @param propertyPath - The property path
+     * @returns Human-readable explanation
+     *
+     * @example
+     * await SemanticUndefined.because("not in response").explain("user.nickname")
+     * // "The nickname property was not included in the API response"
+     */
+    explain(propertyPath: string): Promise<string>;
+    /**
+     * Get the context/reason for this undefined.
+     * Note: This method is named getContext per the spec, but also implements
+     * getReason from SemanticAbsence interface for compatibility.
+     *
+     * @returns The context string or undefined
+     */
+    getContext(): string | undefined;
+    /**
+     * Get the reason for this undefined (alias for getContext).
+     * Implements SemanticAbsence interface.
+     *
+     * @returns The reason string or undefined
+     */
+    getReason(): string | undefined;
+    /**
+     * Check if this is semantically undefined (always true for SemanticUndefined).
+     *
+     * @returns true
+     */
+    isUndefined(): true;
+    /**
+     * Get the underlying undefined value.
+     *
+     * @returns undefined
+     */
+    valueOf(): undefined;
+    /**
+     * Convert to string representation
+     */
+    toString(): string;
+    /**
+     * Convert to JSON representation
+     */
+    toJSON(): {
+        value: undefined;
+        context?: string;
+    };
+}
+//# sourceMappingURL=undefined.d.ts.map

package/dist/primitives/undefined/undefined.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undefined.d.ts","sourceRoot":"","sources":["../../../src/primitives/undefined/undefined.ts"],"names":[],"mappings":"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"}

package/dist/primitives/void/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * SemanticVoid module exports
+ */
+export { SemanticVoid, type VoidFunction, type AnalyzeSideEffectsResult, type ShouldReturnValueResult, type ValidateUsageResult, type CheckErrorHandlingResult, type SuggestSignatureResult, type AppropriateResult, } from './void.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/primitives/void/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/primitives/void/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,WAAW,CAAC"}

package/dist/primitives/void/prompts.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Prompts for SemanticVoid LLM operations
+ * These prompts analyze void functions, side effects, and proper usage patterns
+ */
+/**
+ * System prompt for void function analysis tasks
+ */
+export declare const VOID_SYSTEM_PROMPT = "You are a semantic void function analyzer. Your task is to analyze functions that return void, understand their side effects, and validate their proper usage.\n\nYou must respond with valid JSON only, no additional text or explanation.\n\nKey concepts:\n- Void functions perform side effects without returning values\n- Side effects include: I/O operations, state mutations, logging, network requests, DOM manipulation\n- Pure functions have no side effects and should typically return values\n- Error handling is critical for void functions since errors cannot be returned\n\nGuidelines:\n- Analyze function code to identify all side effects\n- Consider the function name semantics when inferring behavior\n- Provide clear, actionable recommendations\n- Be conservative with safety assessments";
+/**
+ * Prompt template for analyzing side effects of a void function
+ */
+export declare function createAnalyzeSideEffectsPrompt(fnSource: string): string;
+/**
+ * Prompt template for determining if a function should return a value
+ */
+export declare function createShouldReturnValuePrompt(fnSource: string, context?: string): string;
+/**
+ * Prompt template for explaining what a void function does
+ */
+export declare function createExplainPrompt(fnSource: string): string;
+/**
+ * Prompt template for validating usage of a void function
+ */
+export declare function createValidateUsagePrompt(fnSource: string, usage: string): string;
+/**
+ * Prompt template for checking error handling in a void function
+ */
+export declare function createCheckErrorHandlingPrompt(fnSource: string): string;
+/**
+ * Prompt template for suggesting a better function signature
+ */
+export declare function createSuggestSignaturePrompt(fnSource: string): string;
+/**
+ * Prompt template for checking if void is appropriate for a function name
+ */
+export declare function createIsAppropriateForPrompt(fnName: string): string;
+//# sourceMappingURL=prompts.d.ts.map

package/dist/primitives/void/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../../src/primitives/void/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,eAAO,MAAM,kBAAkB,+xBAcW,CAAC;AAE3C;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBvE;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAsBR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAiB5D;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,MAAM,CAqBR;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBvE;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBrE;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAiBnE"}