init geek calc

specs/001-build-a-single/contracts/calculator-contract.md

@@ -0,0 +1,76 @@
+# Calculator Module Interface Contract
+
+## Purpose
+Defines the interface for the core calculator functionality module that will handle all mathematical operations.
+
+## Interface Definition
+
+### Core Calculator API
+```
+interface Calculator {
+  // Evaluate an arithmetic expression in standard notation
+  evaluate(expression: string): number | Error
+  
+  // Add two numbers
+  add(a: number, b: number): number
+  
+  // Subtract two numbers  
+  subtract(a: number, b: number): number
+  
+  // Multiply two numbers
+  multiply(a: number, b: number): number
+  
+  // Divide two numbers (handles division by zero)
+  divide(a: number, b: number): number | Error
+  
+  // Handle percentage operations
+  percentage(value: number, percent: number): number
+  
+  // Toggle sign of a number
+  toggleSign(value: number): number
+  
+  // Clear the current calculation
+  clear(): void
+  
+  // Get current display value
+  getCurrentDisplay(): string
+}
+```
+
+### RPN Calculator API
+```
+interface RPNCalculator {
+  // Push a number onto the stack
+  push(value: number): void
+  
+  // Pop a number from the stack
+  pop(): number | undefined
+  
+  // Perform an operation on stack values
+  operate(operator: string): number | Error
+  
+  // Clear the entire stack
+  clear(): void
+  
+  // Get current stack state
+  getStack(): number[]
+  
+  // Execute RPN expression (e.g., "3 4 +")
+  evaluate(rpnExpression: string): number | Error
+}
+```
+
+### Validation Requirements
+- All operations must return valid numbers or appropriate error objects
+- Division by zero must return an Error object
+- Expression syntax errors must return Error objects
+- Operations must respect JavaScript numeric limits (will return Infinity if exceeded)
+
+### Performance Requirements
+- All operations must complete within 100ms
+- Evaluation should be efficient to maintain responsive UI
+
+### Error Handling
+- Invalid operations return Error objects with descriptive messages
+- Overflow conditions return Infinity values
+- Underflow conditions return 0 values