chore: merge dev to main - core foundation complete

.claude/agent-memory/typescript-expert/MEMORY.md

@@ -0,0 +1,7 @@
+# TypeScript Expert Memory Index
+
+## Reference Documents
+
+- [record-string-unknown-pattern](record-string-unknown-pattern.md) — Senior to Principal TypeScript patterns
+- [stack-capture-patterns](stack-capture-patterns.md) — Stack trace handling patterns
+- [principal-level-error-system](principal-level-error-system.md) — Error factory system design patterns

.claude/agent-memory/typescript-expert/principal-level-error-system.md

@@ -0,0 +1,154 @@
+---
+name: principal-level-error-system
+description: Principal Level patterns for error factory - type inference, runtime validation, polymorphism, branding
+type: reference
+---
+
+# Principal Level: Error Factory System
+
+## 1. Automatic Type Inference from Schema
+
+Automatically extract output type from Standard Schema.
+
+```typescript
+export const error = <
+ const TSchema extends StandardSchemaV1 | undefined = undefined,
+ TData = TSchema extends StandardSchemaV1
+ ? StandardSchemaV1.InferOutput<TSchema>
+ : Record<string, never>
+>(config: {
+ name: string;
+ fields?: TSchema;
+ inherits?: ErrorFactory | ErrorFactory[];
+ message?: string;
+}): ErrorFactory<TData> => { ... }
+
+// Usage - types inferred automatically
+const ValidationError = error({
+ name: 'ValidationError',
+ fields: z.object({ field: z.string() }),
+});
+
+// err.fields.field is automatically typed as string
+```
+
+### Why This Matters
+
+- No manual generic needed
+- Schema drives the entire type system
+- Compile-time validation of required fields
+
+---
+
+## 2. Runtime Contract Enforcement
+
+Always validate input against schema before creating instance.
+
+```typescript
+const ErrorFactoryInstance = (input?: Partial<TData>): ErrorInstance<TData> => {
+ if (fields) {
+ const result = fields['~standard'].validate(input ?? {});
+
+ if (result instanceof Promise) {
+ // Note: async validation not supported in sync factory
+ }
+
+ if (result.issues) {
+ // Throw if provided fields don't match schema
+ // Ensures ErrorInstance never contains invalid data
+ }
+ }
+ // ... rest
+};
+```
+
+### Why This Matters
+
+- `ErrorInstance` is always valid
+- Catch errors early
+- Schema is a true contract
+
+---
+
+## 3. Polymorphism: The `is` Utility
+
+Check inheritance relationships across the chain.
+
+```typescript
+export const is = (err: unknown, factory: ErrorFactory): boolean => {
+ if (!err || typeof err !== 'object' || !('_factory' in err)) {
+ return false;
+ }
+
+ let current: ErrorFactory | ErrorFactory[] | undefined =
+ (err as ErrorInstance)._factory;
+
+ const check = (f: ErrorFactory): boolean => {
+ if (f === factory) return true;
+ if (Array.isArray(f.inherits)) return f.inherits.some(check);
+ if (f.inherits) return check(f.inherits);
+ return false;
+ };
+
+ return check(current as ErrorFactory);
+};
+
+// Usage
+const AppError = error({ name: 'AppError' });
+const ValidationError = error({ name: 'ValidationError', inherits: AppError });
+
+const err = createValidationError();
+is(err, AppError); // ✅ true
+is(err, ValidationError); // ✅ true
+is(err, NetworkError); // ✅ false
+```
+
+### Why This Matters
+
+- `instanceof` doesn't work with plain objects
+- Inheritance is functional, not just metadata
+- Type-safe error checking
+
+---
+
+## 4. Nominal Typing via Branding
+
+Prevent structural type collisions.
+
+```typescript
+export type ErrorInstance<
+ TFields extends Record<string, unknown>,
+ Name extends string
+> = {
+ readonly __brand: Name;
+ name: Name;
+ fields: TFields;
+ // ... other properties
+};
+
+// Usage - errors are nominally typed
+const ValidationError = error({ name: 'ValidationError' });
+const NetworkError = error({ name: 'NetworkError' });
+
+// These are different types even with same shape
+declare function processValidation(err: ErrorInstance<{}, 'ValidationError'>);
+declare function processNetwork(err: ErrorInstance<{}, 'NetworkError'>);
+
+processValidation(NetworkError()); // ❌ Type error
+```
+
+### Why This Matters
+
+- TypeScript uses structural typing by default
+- Branding creates nominal typing
+- Prevents passing wrong error type to functions
+
+---
+
+## Summary Table
+
+| Level | Focus | Key Feature |
+|:---|:---|:---|
+| Senior | Clean utilities | Regex, JSDoc, constants |
+| Staff | Abstraction | StandardSchemaV1, inherits |
+| Principal | Integrity | Auto-inference, runtime validation, is(), branding |

.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md

@@ -0,0 +1,91 @@
+---
+name: record-string-unknown-pattern
+description: TypeScript patterns from Senior to Principal/Staff level
+type: reference
+---
+
+# TypeScript Patterns: Senior to Principal/Staff Level
+
+## Senior Pattern: `T extends Record<string, unknown>`
+
+Use for generic functions accepting dictionary-like objects.
+
+### Why This Pattern
+
+| Pattern | Level | Why |
+|:---|:---|:---|
+| `T extends any` | Junior | No constraint |
+| `T extends object` | Intermediate | Too broad |
+| `T extends Record<string, any>` | Intermediate | Unsafe values |
+| **`T extends Record<string, unknown>`** | **Senior** | Safe + explicit |
+
+### Key Points
+
+1. **`unknown` vs `any`**: Forces type narrowing before use
+2. **`Record` vs `object`**: Explicitly dictionary-like (not arrays/functions)
+3. **Interface Gotcha**: Interfaces lack implicit index signatures
+
+```typescript
+interface UserInterface { name: string }
+type UserType = { name: string }
+
+process<T extends Record<string, unknown>>(obj: T) {}
+process(UserType) // ✅ Works
+process(UserInterface) // ❌ Error
+```
+
+---
+
+## Principal/Staff Pattern: Template Literal Types
+
+Extract keys from template string at compile-time for type-safe data.
+
+```typescript
+type ExtractKeys<S extends string> =
+ S extends `${string}{${infer Key}}${infer Rest}`
+ ? (Key extends `${infer RealKey}:${string}` ? RealKey : Key) | ExtractKeys<Rest>
+ : never;
+
+const formatTemplate = <S extends string>(
+ template: S,
+ data: Record<ExtractKeys<S>, unknown>
+): string => { ... }
+
+// Usage:
+formatTemplate("Hello {name}", { name: "Alice" }); // ✅ Works
+formatTemplate("Hello {name}", { age: 30 }); // ❌ Error: missing 'name'
+```
+
+### Why This Matters
+
+- **Compile-time validation**: Missing keys are caught at compile time
+- **No runtime surprises**: API forces correct usage
+- **Self-documenting**: Template string defines required keys
+
+---
+
+## Senior-Level Regex State Management
+
+Global regex with `/g` flag is stateful. Always reset `lastIndex`:
+
+```typescript
+const REGEX = /\{(\w+)(?::(\w+))?\}/g;
+
+const hasTemplatePlaceholders = (message: string): boolean => {
+ REGEX.lastIndex = 0; // Reset before each use
+ return REGEX.test(message);
+};
+```
+
+**Without reset**: Second call might return `false` even when pattern exists.
+
+---
+
+## Summary of Levels
+
+| Level | Technique | Benefit |
+|:---|:---|:---|
+| Junior | `any`, no constraints | Works, but unsafe |
+| Intermediate | `object`, `Record<string, any>` | Shape correct |
+| Senior | `Record<string, unknown>` | Type-safe |
+| Principal/Staff | Template Literal Types | Compile-time key validation |

.claude/agent-memory/typescript-expert/stack-capture-patterns.md

@@ -0,0 +1,105 @@
+---
+name: stack-capture-patterns
+description: Senior to Expert level patterns for stack trace handling
+type: reference
+---
+
+# Stack Capture Patterns: Senior to Expert Level
+
+## Senior Pattern: String-Based Stack Filtering
+
+Clean up stack traces by filtering internal frames.
+
+```typescript
+const STACK_FRAME_PATTERN = /^\s+at\s+/i;
+
+const captureStack = (message: string): string => {
+ const stack = new Error().stack || '';
+
+ const lines = stack.split('\n');
+ const cleanedLines: string[] = [`Error: ${message}`];
+
+ // Find start index (skip "Error: message" line)
+ let startIndex = 0;
+ for (let i = 0; i < lines.length; i++) {
+ if (STACK_FRAME_PATTERN.test(lines[i])) {
+ startIndex = i;
+ break;
+ }
+ }
+
+ // Filter internal frames
+ for (let i = startIndex; i < lines.length; i++) {
+ const line = lines[i];
+ if (line.includes('node_modules')) continue;
+ if (line.includes('__vite')) continue;
+ cleanedLines.push(line);
+ }
+
+ return cleanedLines.join('\n');
+};
+```
+
+### Key Senior Points
+
+1. **DX Focus**: Hide `node_modules/@deessejs` and `__vite` to show user-relevant frames
+2. **Environmental Awareness**: Document V8-specific nature of `Error.stack`
+3. **Defensive Programming**: Fallback to `|| ''` when stack is undefined
+4. **Maintainable**: Use constants for regex patterns
+
+---
+
+## Expert Pattern: `Error.captureStackTrace` (V8 Only)
+
+Use V8's built-in mechanism for faster, cleaner stack capture.
+
+```typescript
+const captureStack = (message: string): string => {
+ // Check for V8 environment
+ if (typeof Error.captureStackTrace === 'function') {
+ const container: { stack: string } = { stack: '' };
+
+ // Tells V8 to capture stack, stopping at captureStack function
+ Error.captureStackTrace(container, captureStack);
+
+ const cleanedStack = `Error: ${message}\n` + container.stack
+ .split('\n')
+ .slice(1) // Remove captureStack frame
+ .filter(line =>
+ !line.includes('node_modules') &&
+ !line.includes('__vite')
+ )
+ .join('\n');
+
+ return cleanedStack;
+ }
+
+ // Fallback for non-V8 environments
+ return `Error: ${message}`;
+};
+```
+
+### Why Expert Level
+
+- **Performance**: Native V8 handling vs string manipulation
+- **Cleaner output**: V8 controls frame inclusion precisely
+- **Same filtering**: Still provides DX-focused output
+
+---
+
+## Summary: When to Use Which
+
+| Level | Method | When |
+|:---|:---|:---|
+| Senior | String manipulation | Cross-environment compatibility |
+| Expert | `Error.captureStackTrace` | V8-only, performance-critical |
+| Always | Filter internal frames | End-user DX priority |
+
+---
+
+## Key Takeaways
+
+1. **DX First**: Stack traces should point to user code, not library internals
+2. **Document Boundaries**: `Error.stack` is V8-specific, document limitations
+3. **Defensive**: Always handle `undefined` stack cases
+4. **Expert Option**: Use native APIs when available for better performance