groundswell 0.0.2 → 1.0.0

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/architecture/logger_child_signature_analysis.md

@@ -1,401 +0,0 @@
-# Logger child() Signature Analysis
-
-## 1. PRD Specification
-
-### Signature from PRD Section 12.1
-
-```typescript
-child(meta: Partial<LogEntry>): WorkflowLogger {
-  return new WorkflowLogger(this.node, this.observers);
-}
-```
-
-**Source**: PRD.md lines 303-305
-
-### LogEntry Type Definition
-
-```typescript
-export interface LogEntry {
-  /** Unique identifier for this log entry */
-  id: string;
-  /** ID of the workflow that created this log */
-  workflowId: string;
-  /** Unix timestamp in milliseconds */
-  timestamp: number;
-  /** Severity level */
-  level: LogLevel;
-  /** Log message */
-  message: string;
-  /** Optional structured data */
-  data?: unknown;
-  /** ID of parent log entry (for hierarchical logging) */
-  parentLogId?: string;
-}
-```
-
-**Source**: src/types/logging.ts lines 9-24
-
-### PRD Implementation Notes
-
-The PRD skeleton shows that `meta: Partial<LogEntry>` is **accepted but NOT USED** in the implementation. The `child()` method simply returns a new `WorkflowLogger` with the same `node` and `observers`, ignoring the `meta` parameter entirely.
-
-This suggests the parameter is for **future extensibility** - the PRD architect intended to allow passing metadata when creating child loggers, but the skeleton implementation was a stub.
-
----
-
-## 2. Current Implementation
-
-### Actual Signature
-
-```typescript
-child(parentLogId: string): WorkflowLogger
-```
-
-**Source**: src/core/logger.ts line 84
-
-### Current Code
-
-```typescript
-export class WorkflowLogger {
-  private readonly parentLogId?: string;
-
-  constructor(
-    private readonly node: WorkflowNode,
-    private readonly observers: WorkflowObserver[],
-    parentLogId?: string
-  ) {
-    this.parentLogId = parentLogId;
-  }
-
-  /**
-   * Create a child logger that includes parentLogId
-   */
-  child(parentLogId: string): WorkflowLogger {
-    return new WorkflowLogger(this.node, this.observers, parentLogId);
-  }
-}
-```
-
-**Source**: src/core/logger.ts lines 8-16, 84-86
-
-### Constructor Support for parentLogId
-
-The current implementation **does support** hierarchical logging through the constructor:
-
-1. `WorkflowLogger` stores `parentLogId` as a private field
-2. The constructor accepts an optional `parentLogId` parameter
-3. The `child()` method passes the `parentLogId` to the constructor
-4. When logging, if `this.parentLogId` exists, it's added to the log entry:
-
-```typescript
-// From src/core/logger.ts lines 45-48
-if (this.parentLogId) {
-  entry.parentLogId = this.parentLogId;
-}
-```
-
----
-
-## 3. Signature Comparison
-
-### Key Differences Table
-
-| Aspect | PRD Spec | Current Implementation |
-|--------|----------|----------------------|
-| Parameter Type | `Partial<LogEntry>` | `string` |
-| Parameter Name | `meta` | `parentLogId` |
-| Flexibility | Can pass any LogEntry field | Only accepts parentLogId |
-| PRD Skeleton Behavior | Ignores the meta parameter | Uses parentLogId to set hierarchy |
-| Actual Implementation | N/A (skeleton only) | Passes parentLogId to constructor |
-
-### Compatibility Matrix
-
-| Call Pattern | Works with PRD Spec | Works with Current Implementation |
-|--------------|-------------------|----------------------------------|
-| `logger.child('parent-id')` | No (wrong type) | Yes |
-| `logger.child({ parentLogId: 'parent-id' })` | Yes | No |
-| `logger.child({})` | Yes | No |
-| `logger.child({ id: 'custom-id', parentLogId: 'parent-id' })` | Yes | No |
-
-**Result**: Complete incompatibility - the two signatures are mutually exclusive.
-
----
-
-## 4. Existing Usage Analysis
-
-### Usage Site 1: deep-analysis.test.ts:61
-
-```typescript
-const childLogger = this.logger.child('');
-childLogger.info('Child log with empty parent');
-```
-
-**Context**: Testing empty parentLogId handling
-
-**Expected Behavior**: Empty string is passed through, and because of the falsy check in the logger's `log()` method, `parentLogId` remains `undefined`.
-
-**Impact**: BREAKING - will need migration
-
-**Migration Path**:
-```typescript
-// Before
-const childLogger = this.logger.child('');
-
-// After
-const childLogger = this.logger.child({ parentLogId: '' });
-// Or for root logger behavior:
-const childLogger = this.logger.child({});
-```
-
-### Usage Site 2: edge-case.test.ts:96
-
-```typescript
-const childLogger = this.logger.child('parent-id-123');
-expect(childLogger).toBeDefined();
-```
-
-**Context**: Testing normal parentLogId passing and verifying child logger is created
-
-**Expected Behavior**: Child logger stores `'parent-id-123'` as its parentLogId, which gets attached to all log entries from this child logger.
-
-**Impact**: BREAKING - will need migration
-
-**Migration Path**:
-```typescript
-// Before
-const childLogger = this.logger.child('parent-id-123');
-
-// After
-const childLogger = this.logger.child({ parentLogId: 'parent-id-123' });
-```
-
-### Usage Summary
-
-- **Total Usage Sites**: 2 test files
-- **Both Are Breaking Changes**: String parameter is incompatible with object parameter
-- **Migration Required**: Both test files will need updates
-
----
-
-## 5. Partial<LogEntry> Field Analysis
-
-### Fields That Make Sense for child()
-
-| Field | Type | Relevance | Notes |
-|-------|------|-----------|-------|
-| `parentLogId` | `string` | **Primary** | Main use case - links child log entries to parent |
-| `id` | `string` | Low | Could allow explicit child log ID, but logger generates IDs automatically |
-| `workflowId` | `string` | Low | Could allow different workflow context, but logger uses `this.node.id` |
-| `data` | `unknown` | Medium | Could attach metadata to child logger for inclusion in all logs |
-| `level` | `LogLevel` | Medium | Could set default level for child logger |
-
-### Fields That DON'T Make Sense
-
-| Field | Type | Why It Doesn't Make Sense |
-|-------|------|---------------------------|
-| `timestamp` | `number` | Child logger generates timestamps when logging, not at creation |
-| `message` | `string` | Logger doesn't have a default message - messages are provided per log call |
-
----
-
-## 6. Recommended Implementation Approach
-
-### Option 1: Strict PRD Compliance (Breaking Change)
-
-```typescript
-child(meta: Partial<LogEntry>): WorkflowLogger {
-  // Extract parentLogId from meta
-  const parentLogId = meta.parentLogId;
-  return new WorkflowLogger(this.node, this.observers, parentLogId);
-}
-```
-
-**Pros**:
-- Matches PRD exactly
-- Enables future extensibility for other meta fields
-- More consistent with TypeScript patterns
-
-**Cons**:
-- Breaking change for 2 existing test files
-- Requires user code migration
-
-**Migration Required**:
-```typescript
-// All existing calls must change from:
-logger.child('parent-id')
-// To:
-logger.child({ parentLogId: 'parent-id' })
-```
-
-### Option 2: Backward Compatible with Overload
-
-```typescript
-// Legacy signature for backward compatibility
-child(parentLogId: string): WorkflowLogger;
-// New PRD-compliant signature
-child(meta: Partial<LogEntry>): WorkflowLogger;
-
-child(input: string | Partial<LogEntry>): WorkflowLogger {
-  const parentLogId = typeof input === 'string'
-    ? input
-    : input.parentLogId;
-  return new WorkflowLogger(this.node, this.observers, parentLogId);
-}
-```
-
-**Pros**:
-- No breaking change
-- Supports both old and new patterns
-- Smooth migration path
-
-**Cons**:
-- More complex implementation
-- TypeScript type narrowing required at call sites
-- Ambiguity: what if someone passes `{ parentLogId: '123' }` vs `'123'`?
-
-### Option 3: Hybrid Approach with Default
-
-```typescript
-child(meta: Partial<LogEntry> = {}): WorkflowLogger {
-  const parentLogId = meta.parentLogId;
-  return new WorkflowLogger(this.node, this.observers, parentLogId);
-}
-```
-
-**Pros**:
-- Default empty object makes `logger.child()` calls work
-- Closer to PRD signature
-
-**Cons**:
-- Still breaking for string-based calls like `logger.child('parent-id')`
-- Doesn't solve the incompatibility problem
-
-### Recommendation: **Option 1 - Strict PRD Compliance**
-
-**Rationale**:
-
-1. **Codebase Pattern**: This project has a history of breaking changes when correcting PRD mismatches. See CHANGELOG.md for the `attachChild()` behavior change which also broke existing patterns.
-
-2. **Limited Impact**: Only 2 test files are affected. The public API impact is minimal since this is primarily used internally.
-
-3. **Future Extensibility**: The `Partial<LogEntry>` signature allows passing additional metadata (like `data`, `level`) in future enhancements without another breaking change.
-
-4. **Type Safety**: The object-based signature is more self-documenting and type-safe than a string parameter.
-
-5. **Consistency**: Aligning implementation with PRD specification is the correct architectural decision.
-
----
-
-## 7. Migration Strategy
-
-### Code Changes Required
-
-1. **Update src/core/logger.ts:84** - Change `child()` signature
-2. **Update 2 test files** - Convert to object syntax
-3. **Update documentation** - Document the new signature
-
-### Test Migration Examples
-
-#### Test File 1: src/__tests__/adversarial/deep-analysis.test.ts:61
-
-```typescript
-// Before
-const childLogger = this.logger.child('');
-childLogger.info('Child log with empty parent');
-
-// After
-const childLogger = this.logger.child({});
-childLogger.info('Child log with empty parent');
-```
-
-#### Test File 2: src/__tests__/adversarial/edge-case.test.ts:96
-
-```typescript
-// Before
-const childLogger = this.logger.child('parent-id-123');
-expect(childLogger).toBeDefined();
-
-// After
-const childLogger = this.logger.child({ parentLogId: 'parent-id-123' });
-expect(childLogger).toBeDefined();
-```
-
-### Implementation Template for P1.M1.T1.S2
-
-```typescript
-/**
- * Create a child logger that includes parentLogId
- * @param meta Partial log entry metadata (typically { parentLogId: string })
- */
-child(meta: Partial<LogEntry> = {}): WorkflowLogger {
-  const parentLogId = meta.parentLogId;
-  return new WorkflowLogger(this.node, this.observers, parentLogId);
-}
-```
-
-**Note**: The default parameter `{}` allows `logger.child()` to be called without arguments, creating a logger with no parentLogId (similar to current empty string behavior).
-
----
-
-## 8. Related Files
-
-| File | Lines | Purpose |
-|------|-------|---------|
-| PRD.md | 286-307 | PRD Section 12.1 WorkflowLogger specification |
-| src/core/logger.ts | 8-16, 84-86 | Current WorkflowLogger implementation with child() |
-| src/types/logging.ts | 9-24 | LogEntry interface definition |
-| src/__tests__/adversarial/deep-analysis.test.ts | 61 | Usage site 1: empty string parentLogId |
-| src/__tests__/adversarial/edge-case.test.ts | 96 | Usage site 2: normal parentLogId |
-| src/types/reflection.ts | 110-117 | Partial<T> usage pattern reference |
-
-### Partial<T> Pattern Reference from reflection.ts
-
-```typescript
-export function createReflectionConfig(
-  partial?: Partial<ReflectionConfig>
-): ReflectionConfig {
-  return {
-    ...DEFAULT_REFLECTION_CONFIG,  // Spread defaults first
-    ...partial,                     // Then override with provided values
-  };
-}
-```
-
-**Pattern Note**: This shows the codebase uses spread operator for merging Partial objects. Similar pattern could be applied if child() needs to merge multiple metadata fields in the future.
-
----
-
-## Summary
-
-### Core Issue
-
-The `child()` method signature is **incompatible** between PRD specification and current implementation:
-
-- **PRD**: `child(meta: Partial<LogEntry>)`
-- **Actual**: `child(parentLogId: string)`
-
-### Impact Assessment
-
-- **Breaking Change**: Yes - string and object types are incompatible
-- **Affected Files**: 2 test files (minimal impact)
-- **Public API Impact**: Low - primarily internal usage
-
-### Recommended Action
-
-**Implement Option 1 (Strict PRD Compliance)** in the next subtask (P1.M1.T1.S2):
-
-1. Update `src/core/logger.ts:84` to accept `Partial<LogEntry>`
-2. Migrate the 2 test files to use object syntax
-3. Add a default parameter `{}` to allow `logger.child()` calls without arguments
-
-### Next Steps
-
-1. **P1.M1.T1.S2** - Implement the signature change in `src/core/logger.ts`
-2. **P1.M1.T1.S3** - Add tests for the new `child()` signature with `Partial<LogEntry>`
-3. **P1.M1.T1.S4** - Verify all existing `child()` calls work after migration
-
----
-
-**Document Version**: 1.0
-**Generated**: 2026-01-12
-**For**: P1.M1.T1.S2 - Update WorkflowLogger.child() to accept Partial<LogEntry>

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M1T1S3/child_implementation_research.md

@@ -1,142 +0,0 @@
-# child() Implementation Research
-
-## File Location
-
-**Path**: `/home/dustin/projects/groundswell/src/core/logger.ts`
-**Lines**: 81-94 (child() method)
-
-## Current child() Method Implementation
-
-```typescript
-/**
- * Create a child logger that includes parentLogId
- * @param parentLogId - ID of the parent log entry (legacy API)
- */
-child(parentLogId: string): WorkflowLogger;
-/**
- * Create a child logger with metadata
- * @param meta - Partial log entry metadata (typically { parentLogId: string })
- */
-child(meta: Partial<LogEntry>): WorkflowLogger;
-child(input: string | Partial<LogEntry>): WorkflowLogger {
-  const parentLogId = typeof input === 'string' ? input : input.parentLogId;
-  return new WorkflowLogger(this.node, this.observers, parentLogId);
-}
-```
-
-## LogEntry Type Definition
-
-**Path**: `/home/dustin/projects/groundswell/src/types/logging.ts`
-**Lines**: 9-24
-
-```typescript
-export interface LogEntry {
-  id: string;                  // Unique identifier for this log entry
-  workflowId: string;          // ID of the workflow that created this log
-  timestamp: number;           // Unix timestamp in milliseconds
-  level: LogLevel;             // Severity level
-  message: string;             // Log message
-  data?: unknown;              // Optional structured data
-  parentLogId?: string;        // ID of parent log entry (for hierarchical logging)
-}
-
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-```
-
-## child() Method Behavior by Input Type
-
-### Scenario 1: Partial<LogEntry> containing parentLogId
-```typescript
-// Input: { parentLogId: 'some-id' }
-const childLogger = logger.child({ parentLogId: 'some-id' });
-
-// Behavior:
-// - Type guard returns false (not a string)
-// - input.parentLogId is extracted ('some-id')
-// - New WorkflowLogger created with parentLogId = 'some-id'
-// - All log entries from this child will have parentLogId = 'some-id'
-```
-
-### Scenario 2: Partial<LogEntry> containing id (should use as parentLogId)
-```typescript
-// Input: { id: 'some-id' }
-const childLogger = logger.child({ id: 'some-id' });
-
-// Behavior:
-// - Type guard returns false
-// - input.parentLogId is undefined (object only has id)
-// - New WorkflowLogger created with parentLogId = undefined
-// - All log entries from this child will NOT have a parentLogId
-```
-
-### Scenario 3: String input (backward compatibility)
-```typescript
-// Input: 'parent-id-123'
-const childLogger = logger.child('parent-id-123');
-
-// Behavior:
-// - Type guard returns true
-// - input is assigned directly as parentLogId
-// - New WorkflowLogger created with parentLogId = 'parent-id-123'
-// - All log entries from this child will have parentLogId = 'parent-id-123'
-```
-
-### Scenario 4: Empty object (should generate parentLogId)
-```typescript
-// Input: {}
-const childLogger = logger.child({});
-
-// Behavior:
-// - Type guard returns false
-// - input.parentLogId is undefined (empty object has no properties)
-// - New WorkflowLogger created with parentLogId = undefined
-// - All log entries from this child will NOT have a parentLogId
-```
-
-## How parentLogId is Set in Child Logger Entries
-
-**Location**: `src/core/logger.ts` lines 45-48
-
-```typescript
-// Add parent log ID if this is a child logger
-if (this.parentLogId) {
-  entry.parentLogId = this.parentLogId;
-}
-```
-
-**Process**:
-1. When logging (lines 35-51), a new LogEntry is created with `generateId()`
-2. If `this.parentLogId` exists (is truthy), it's added to the entry
-3. The entry is then emitted to the node and observers
-4. **Note**: Empty strings (`''`) are falsy, so `parentLogId: ''` becomes `undefined`
-
-## Constructor Support
-
-```typescript
-// Line 8-16
-export class WorkflowLogger {
-  private readonly parentLogId?: string;
-
-  constructor(
-    private node: WorkflowNode,
-    private observers: WorkflowObserver[],
-    parentLogId?: string
-  ) {
-    this.parentLogId = parentLogId;
-  }
-  // ...
-}
-```
-
-## Key Implementation Details
-
-1. **Function Overloads**: Two overload signatures for backward compatibility
-2. **Type Guard**: Uses `typeof input === 'string'` to narrow union type
-3. **Falsy Handling**: Empty strings are treated as undefined due to falsy check in `log()` method
-4. **PRD Compliance**: Matches PRD specification with backward-compatible overloads
-5. **Future Extensibility**: Accepts additional fields in `Partial<LogEntry>` but only uses `parentLogId`
-
-## Existing Usage Sites
-
-1. **deep-analysis.test.ts:61**: `this.logger.child('')` - Tests empty string handling
-2. **edge-case.test.ts:96**: `this.logger.child('parent-id-123')` - Tests normal parent ID

package/plan/001_d3bb02af4886/bugfix/001_e8e04329daf3/docs/P1M1T1S3/test_patterns_research.md

@@ -1,112 +0,0 @@
-# Logger Test Patterns Research
-
-## Codebase Test Pattern Analysis
-
-### Existing Test Files Using Logger
-
-| File | Lines | Pattern | Purpose |
-|------|-------|---------|---------|
-| src/__tests__/unit/workflow.test.ts | Basic logging | Observer pattern | Tests log emission to observers |
-| src/__tests__/adversarial/deep-analysis.test.ts | 61 | `this.logger.child('')` | Tests empty parentLogId handling |
-| src/__tests__/adversarial/edge-case.test.ts | 96 | `this.logger.child('parent-id-123')` | Tests normal parent ID passing |
-
-### Vitest Configuration
-
-```typescript
-// vitest.config.ts
-export default defineConfig({
-  test: {
-    include: ['src/__tests__/**/*.test.ts'],
-    globals: true,
-  },
-  esbuild: {
-    target: 'node18',
-  },
-});
-```
-
-### Test Scripts
-
-```json
-// package.json
-{
-  "test": "vitest run",
-  "test:watch": "vitest"
-}
-```
-
-### Key Test Patterns
-
-#### 1. Basic Logging Test Pattern
-```typescript
-it('should emit logs to observers', async () => {
-  const wf = new SimpleWorkflow();
-  const logs: LogEntry[] = [];
-
-  const observer: WorkflowObserver = {
-    onLog: (entry) => logs.push(entry),
-    onEvent: () => {},
-    onStateUpdated: () => {},
-    onTreeChanged: () => {},
-  };
-
-  wf.addObserver(observer);
-  await wf.run();
-
-  expect(logs.length).toBeGreaterThan(0);
-  expect(logs[0].message).toBe('Running simple workflow');
-});
-```
-
-#### 2. Child Logger Test Pattern
-```typescript
-it('should handle logger.child() with empty parentLogId', async () => {
-  class TestWorkflow extends Workflow {
-    async run() {
-      const childLogger = this.logger.child('');
-      childLogger.info('Child log with empty parent');
-    }
-  }
-
-  const workflow = new TestWorkflow();
-  await workflow.run();
-
-  expect(workflow.node.logs.length).toBe(1);
-  expect(workflow.node.logs[0].parentLogId).toBeUndefined();
-});
-```
-
-#### 3. Mock Pattern for Console
-```typescript
-beforeEach(() => {
-  vi.spyOn(console, 'log').mockImplementation(() => {});
-  vi.spyOn(console, 'error').mockImplementation(() => {});
-});
-
-afterEach(() => {
-  vi.restoreAllMocks();
-});
-```
-
-### Test File Naming Conventions
-
-- Unit tests: `[feature].test.ts` (e.g., `workflow.test.ts`)
-- Adversarial tests: `[topic].test.ts` (e.g., `deep-analysis.test.ts`)
-- Integration tests: `[scenario].test.ts`
-
-### parentLogId Verification Pattern
-```typescript
-// Direct access to node logs
-expect(workflow.node.logs.length).toBe(1);
-expect(workflow.node.logs[0].parentLogId).toBeUndefined();
-// OR
-expect(workflow.node.logs[0].parentLogId).toBe('expected-id');
-```
-
-### Gaps Identified
-
-1. **No dedicated logger test file** - Tests scattered across multiple files
-2. **No comprehensive child() method tests** - Only one adversarial test exists
-3. **No parent-child hierarchy tests** - Tests don't verify parentLogId propagation
-4. **No logger method variants tested** - Only `info` method commonly tested
-5. **No backward compatibility tests** - No tests covering multiple call patterns