@63klabs/cache-data 1.3.8 → 1.3.10

package/AGENTS.md

@@ -1,1012 +0,0 @@
-# AI Development Context & Guidelines for This Repository
-
-This document provides essential context for AI coding assistants working within this repository.
-
-It outlines architectural principles, constraints, naming conventions, and deployment workflows.
-
-All code and infrastructure generated by AI must follow these standards.
-
-**CRITICAL**: This is an NPM package (@63klabs/cache-data) used by external applications. Backwards compatibility is paramount. Breaking changes require major version bumps and migration guides.
-
-## 1. Purpose of This Repository
-
-This repository contains the **@63klabs/cache-data NPM package** - a distributed, serverless data caching solution for AWS Lambda Node.js functions. The package provides:
-
-- **Cache Module**: Distributed caching using DynamoDB and S3 with optional in-memory caching
-- **Endpoint Module**: HTTP/HTTPS request handling with built-in retry logic and caching
-- **Tools Module**: Logging, debugging, request handling, AWS integration, and utility functions
-
-This package is used in production environments handling over 1 million requests per week.
-
-## 2. Critical Constraints
-
-### 2.1 Backwards Compatibility (HIGHEST PRIORITY)
-
-**NEVER break backwards compatibility without explicit user approval and proper versioning.**
-
-- All public APIs must remain stable across minor and patch versions
-- Function signatures cannot change without deprecation warnings
-- Parameter names in JSDoc must match actual function parameters exactly
-- Default behaviors cannot change in ways that affect existing users
-- Environment variable names and behaviors must remain consistent
-- Exported classes, functions, and constants must maintain their interfaces
-
-**Before making ANY change to public APIs:**
-1. Check if the function/class is exported in `src/index.js`
-2. Search for usage in tests to understand expected behavior
-3. Consider if existing applications would break
-4. If breaking change is necessary, discuss with user first
-
-**Deprecation Process:**
-1. Add `@deprecated` JSDoc tag with migration instructions
-2. Log deprecation warnings when deprecated features are used
-3. Update CHANGELOG.md with deprecation notice
-4. Maintain deprecated functionality for at least one major version
-5. Provide clear migration path in documentation
-
-### 2.2 Semantic Versioning
-
-This package follows strict semantic versioning (semver):
-
-- **MAJOR** (x.0.0): Breaking changes, API changes, removed features
-- **MINOR** (1.x.0): New features, new APIs, backwards-compatible additions
-- **PATCH** (1.3.x): Bug fixes, documentation updates, internal improvements
-
-Current version: **1.3.6** (from package.json)
-
-**Version Bump Guidelines:**
-- Bug fixes that don't change behavior: PATCH
-- New optional parameters with defaults: MINOR
-- New classes or functions: MINOR
-- Changed function signatures: MAJOR
-- Removed or renamed exports: MAJOR
-- Changed default behaviors: MAJOR
-
-### 2.3 Testing Requirements
-
-**ALL changes must include appropriate tests. No exceptions.**
-
-#### Test Types Required:
-
-1. **Unit Tests** (Required for all new functions/classes)
-   - Test specific examples and expected behavior
-   - Test edge cases (null, undefined, empty, boundary values)
-   - Test error conditions and error messages
-   - Use descriptive test names
-   - Located in `test/` directory matching source structure
-
-2. **Property-Based Tests** (Required for core logic)
-   - Test universal properties across many inputs
-   - Use fast-check library for property generation
-   - Validate invariants and mathematical properties
-   - Located in `test/*/property/` directories
-
-3. **Integration Tests** (Required for module interactions)
-   - Test interactions between classes/modules
-   - Test AWS service integrations (with mocks)
-   - Test end-to-end workflows
-   - Located in `test/*/integration/` directories
-
-#### Test Execution:
-
-```bash
-# Run all tests
-npm test
-
-# Run specific test suites
-npm run test:cache
-npm run test:config
-npm run test:endpoint
-npm run test:logging
-npm run test:request
-npm run test:response
-npm run test:utils
-```
-
-#### Test Requirements Before Merging:
-
-- [ ] All existing tests pass
-- [ ] New tests added for new functionality
-- [ ] Property-based tests added for core logic
-- [ ] Edge cases covered
-- [ ] Error conditions tested
-- [ ] No test coverage regression
-- [ ] Tests are deterministic (no flaky tests)
-
-**CRITICAL**: If tests fail, fix the code OR the test. Never ignore failing tests. Tests may reveal bugs in code - don't assume code is always correct.
-
-### 2.4 Documentation Requirements
-
-**ALL public APIs must have complete JSDoc documentation.**
-
-See `.kiro/steering/documentation-standards.md` for complete documentation standards.
-
-#### Required JSDoc Tags:
-
-**For Functions/Methods:**
-- Description (no tag, just text)
-- `@param` for each parameter with type and description
-- `@returns` with type and description (omit only for void)
-- `@example` with at least one working code example
-- `@throws` for each error type that can be thrown
-
-**For Classes:**
-- Description of purpose and responsibilities
-- `@param` for constructor parameters
-- `@example` showing instantiation and common usage
-- `@property` for public properties
-
-#### Documentation Update Checklist:
-
-- [ ] JSDoc added/updated for all public APIs
-- [ ] Parameter names match function signatures exactly
-- [ ] Return types match actual return values
-- [ ] Examples are executable and correct
-- [ ] User documentation updated if behavior changed
-- [ ] CHANGELOG.md updated with user-facing changes
-- [ ] All documentation validation tests pass
-
-#### Run Documentation Validation:
-
-```bash
-# Run all documentation tests
-npm test -- test/documentation/
-
-# Run documentation audit
-node scripts/audit-documentation.mjs
-```
-
-**CRITICAL**: Documentation must be accurate. No hallucinations. Every documented feature must exist in the implementation.
-
-## 3. Architecture and Code Organization
-
-### 3.1 Module Structure
-
-The package is organized into three main modules:
-
-```
-src/
-├── index.js                 # Main entry point, exports tools, cache, endpoint
-├── lib/
-│   ├── dao-cache.js        # Cache module (S3Cache, DynamoDbCache, CacheData, Cache)
-│   ├── dao-endpoint.js     # Endpoint module (Endpoint class, get function)
-│   ├── tools/              # Tools module
-│   │   ├── index.js        # Tools entry point
-│   │   ├── AWS.classes.js  # AWS SDK wrappers
-│   │   ├── APIRequest.class.js
-│   │   ├── ClientRequest.class.js
-│   │   ├── Response.class.js
-│   │   ├── ResponseDataModel.class.js
-│   │   ├── Timer.class.js
-│   │   ├── DebugAndLog.class.js
-│   │   ├── ImmutableObject.class.js
-│   │   ├── Connections.classes.js
-│   │   ├── CachedParametersSecrets.classes.js
-│   │   ├── RequestInfo.class.js
-│   │   ├── generic.response.*.js
-│   │   ├── utils.js
-│   │   └── vars.js
-│   └── utils/
-│       └── InMemoryCache.js
-```
-
-### 3.2 Separation of Concerns
-
-**CRITICAL**: Maintain clear separation between modules and classes.
-
-#### Cache Module (`dao-cache.js`):
-- **S3Cache**: Low-level S3 storage operations only
-- **DynamoDbCache**: Low-level DynamoDB storage operations only
-- **CacheData**: Cache management, encryption, expiration logic
-- **Cache**: Public API, cache profiles, configuration
-
-**DO NOT**:
-- Add endpoint logic to cache classes
-- Add cache logic to endpoint classes
-- Mix storage operations with business logic
-- Add AWS SDK calls outside of designated classes
-
-#### Endpoint Module (`dao-endpoint.js`):
-- **Endpoint**: HTTP request handling and response parsing
-- **get()**: Public API function
-
-**DO NOT**:
-- Add cache logic to endpoint classes
-- Add business logic to request handling
-- Mix concerns between modules
-
-#### Tools Module (`tools/`):
-- Each class has a single, well-defined responsibility
-- Utility functions are pure and stateless
-- AWS SDK wrappers isolate AWS-specific code
-
-**DO NOT**:
-- Create god classes with multiple responsibilities
-- Add business logic to utility functions
-- Mix AWS SDK versions (use v3 only)
-
-### 3.3 Class Design Principles
-
-1. **Single Responsibility**: Each class does one thing well
-2. **Static vs Instance**: Use static for stateless operations, instance for stateful
-3. **Initialization**: Static classes use `init()` method, called once at boot
-4. **Private Fields**: Use `#` prefix for private static/instance fields
-5. **Immutability**: Prefer immutable objects where possible
-6. **Error Handling**: Always handle errors gracefully, log appropriately
-
-### 3.4 Adding New Functionality
-
-**Before adding new methods or classes:**
-
-1. **Check for existing functionality**
-   - Search codebase for similar functionality
-   - Check if existing classes can be extended
-   - Avoid duplication at all costs
-
-2. **Determine proper location**
-   - Does it belong in cache, endpoint, or tools?
-   - Is it a new class or method on existing class?
-   - Should it be public or private?
-
-3. **Follow existing patterns**
-   - Match naming conventions
-   - Use similar parameter structures
-   - Follow error handling patterns
-   - Maintain consistency with existing code
-
-4. **Consider backwards compatibility**
-   - Will this break existing code?
-   - Can it be added without breaking changes?
-   - Does it need a deprecation path?
-
-**Example: Adding a new cache method**
-
-```javascript
-// GOOD: Follows existing patterns
-/**
- * Clear all expired cache entries from storage.
- * 
- * @returns {Promise<{success: boolean, count: number}>} Result with count of cleared entries
- * @example
- * const result = await Cache.clearExpired();
- * console.log(`Cleared ${result.count} expired entries`);
- */
-static async clearExpired() {
-    // Implementation
-}
-
-// BAD: Breaks patterns, unclear purpose
-static async doCleanup(opts) {
-    // Implementation
-}
-```
-
-## 4. Code Quality Standards
-
-### 4.1 Code Style
-
-- **Language**: JavaScript (Node.js >= 20.0.0)
-- **Indentation**: Tabs (not spaces)
-- **Quotes**: Double quotes for strings
-- **Semicolons**: Required
-- **Line Length**: Reasonable (no strict limit, but keep readable)
-- **Comments**: Use JSDoc for public APIs, inline comments for complex logic
-
-### 4.2 Naming Conventions
-
-**Classes**: PascalCase
-```javascript
-class CacheData { }
-class S3Cache { }
-class APIRequest { }
-```
-
-**Functions/Methods**: camelCase
-```javascript
-async function getData() { }
-static async read(idHash) { }
-```
-
-**Constants**: UPPER_SNAKE_CASE
-```javascript
-static PRIVATE = "private";
-static PUBLIC = "public";
-static STATUS_NO_CACHE = "original";
-```
-
-**Private Fields**: # prefix
-```javascript
-static #bucket = null;
-#syncedNowTimestampInSeconds = 0;
-```
-
-**Parameters**: camelCase
-```javascript
-function processData(idHash, syncedNow, bodyContent) { }
-```
-
-### 4.3 Error Handling
-
-**ALWAYS handle errors gracefully:**
-
-```javascript
-// GOOD: Proper error handling
-try {
-    const result = await someOperation();
-    return result;
-} catch (error) {
-    tools.DebugAndLog.error(`Operation failed: ${error?.message || 'Unknown error'}`, error?.stack);
-    return defaultValue;
-}
-
-// BAD: Unhandled errors
-const result = await someOperation(); // Could throw
-```
-
-**Error Logging:**
-- Use `tools.DebugAndLog.error()` for errors
-- Include context (what operation failed)
-- Include error message and stack trace
-- Return sensible defaults on error
-
-**Throwing Errors:**
-- Only throw for unrecoverable errors
-- Document with `@throws` JSDoc tag
-- Use descriptive error messages
-- Include context in error message
-
-### 4.4 Performance Considerations
-
-This package is used in high-traffic Lambda functions. Performance matters.
-
-**DO**:
-- Minimize AWS SDK calls
-- Use Promise.all() for parallel operations
-- Cache expensive computations
-- Use in-memory cache when appropriate
-- Minimize JSON.stringify() calls (see existing specs)
-
-**DON'T**:
-- Make synchronous blocking calls
-- Create unnecessary objects in loops
-- Perform expensive operations in constructors
-- Make redundant AWS API calls
-
-### 4.5 Security Considerations
-
-**CRITICAL**: This package handles sensitive data and encryption.
-
-**DO**:
-- Encrypt sensitive data using CacheData encryption
-- Use secure random for IVs and keys
-- Validate all inputs
-- Sanitize data before logging
-- Use environment variables for secrets (never hardcode)
-
-**DON'T**:
-- Log sensitive data (keys, passwords, PII)
-- Store unencrypted sensitive data
-- Trust user input without validation
-- Expose internal implementation details
-
-## 5. Testing Strategy
-
-### 5.1 Test Framework Migration
-
-**CRITICAL: Mocha to Jest Migration in Progress**
-
-This project is actively migrating from Mocha to Jest. During this transition period:
-
-**Migration Status:**
-- **Phase**: Active migration - both frameworks supported
-- **Legacy**: Mocha tests (`*-tests.mjs`) - maintain but don't create new
-- **Current**: Jest tests (`*.jest.mjs`) - all new tests must use this
-- **Goal**: Complete migration to Jest, remove Mocha dependency
-
-**File Naming Conventions:**
-- Mocha (legacy): `cache-tests.mjs`, `endpoint-tests.mjs`, `*-property-tests.mjs`
-- Jest (current): `cache-tests.jest.mjs`, `endpoint-tests.jest.mjs`, `*-property-tests.jest.mjs`
-
-**Test Execution Commands:**
-```bash
-# Run Mocha tests only (legacy)
-npm test
-
-# Run Jest tests only (current)
-npm run test:jest
-
-# Run both test suites (REQUIRED for CI/CD)
-npm run test:all
-
-# Run specific test suites
-npm run test:cache        # Mocha cache tests
-npm run test:cache:jest   # Jest cache tests
-npm run test:endpoint     # Mocha endpoint tests
-npm run test:endpoint:jest # Jest endpoint tests
-```
-
-**Migration Guidelines:**
-
-1. **Creating New Tests:**
-   - ALWAYS use Jest (`*.jest.mjs` files)
-   - Follow Jest patterns and assertions
-   - Use Jest mocking (not Sinon)
-   - Place in same directory as Mocha tests
-
-2. **Modifying Existing Tests:**
-   - If minor change: Update Mocha test
-   - If major change: Consider migrating to Jest
-   - If time permits: Migrate to Jest and delete Mocha version
-
-3. **Test Coverage:**
-   - Both test suites must pass in CI/CD
-   - Jest coverage: `coverage-jest/` directory
-   - Mocha coverage: `coverage/` directory (if generated)
-
-4. **Property-Based Tests:**
-   - Use fast-check in both Mocha and Jest
-   - Same property definitions work in both frameworks
-   - Migrate property tests to Jest when possible
-
-**Why Jest?**
-- Better ESM support
-- Built-in mocking (no Sinon needed)
-- Better async/await handling
-- More modern and actively maintained
-- Better IDE integration
-- Simpler configuration
-
-**Migration Checklist for Converting Tests:**
-- [ ] Create new `*.jest.mjs` file
-- [ ] Import from `@jest/globals` instead of `chai`
-- [ ] Change `expect().to.equal()` to `expect().toBe()`
-- [ ] Change `expect().to.not.equal()` to `expect().not.toBe()`
-- [ ] Replace Sinon mocks with Jest mocks
-- [ ] Update async test patterns if needed
-- [ ] Run Jest tests to verify: `npm run test:jest`
-- [ ] Delete old Mocha test file
-- [ ] Update any references in documentation
-
-### 5.2 Test Organization
-
-Tests mirror source structure:
-
-```
-test/
-├── cache/                  # Cache module tests
-│   ├── cache-tests.mjs (Mocha - legacy)
-│   ├── cache-tests.jest.mjs (Jest - new)
-│   ├── in-memory-cache/
-│   │   ├── unit/
-│   │   ├── integration/
-│   │   └── property/
-├── config/                 # Configuration tests
-├── documentation/          # Documentation validation
-│   └── property/
-├── endpoint/               # Endpoint module tests
-│   ├── endpoint-tests.mjs (Mocha - legacy)
-│   ├── endpoint-tests.jest.mjs (Jest - new)
-├── logging/                # Logging tests
-├── request/                # Request handling tests
-├── response/               # Response tests
-├── utils/                  # Utility tests
-└── helpers/                # Test utilities
-```
-
-**Note**: During migration, both `.mjs` (Mocha) and `.jest.mjs` (Jest) files coexist in the same directories.
-
-### 5.3 Test Naming Conventions
-
-**Mocha (Legacy):**
-- Test files: `*-tests.mjs`
-- Property tests: `*-property-tests.mjs`
-- Integration tests: `*-integration-tests.mjs`
-- Unit tests: `*-unit-tests.mjs` or `*-tests.mjs`
-
-**Jest (Current - Use for All New Tests):**
-- Test files: `*.jest.mjs`
-- Property tests: `*-property-tests.jest.mjs`
-- Integration tests: `*-integration-tests.jest.mjs`
-- Unit tests: `*-unit-tests.jest.mjs` or `*.jest.mjs`
-
-### 5.4 Test Framework
-
-**CRITICAL: Test Framework Migration in Progress**
-
-This project is currently migrating from Mocha to Jest. Both frameworks are supported during the transition period.
-
-**Current Status:**
-- **Legacy Tests**: Mocha tests (files ending in `-tests.mjs`)
-- **New Tests**: Jest tests (files ending in `.jest.mjs`)
-- **Migration Goal**: All tests will eventually be in Jest
-
-**Test Framework by Type:**
-
-**Mocha (Legacy - Being Phased Out):**
-- Test Runner: Mocha
-- Assertions: Chai (expect style)
-- Property Testing: fast-check
-- Mocking: Sinon
-- HTTP Testing: chai-http
-- File Pattern: `*-tests.mjs`
-
-**Jest (Current - All New Tests):**
-- Test Runner: Jest
-- Assertions: Jest built-in (expect)
-- Property Testing: fast-check (same as Mocha)
-- Mocking: Jest built-in
-- HTTP Testing: Jest with mocks
-- File Pattern: `*.jest.mjs`
-
-**Rules for Test Development:**
-
-1. **ALL NEW TESTS MUST BE WRITTEN IN JEST** using the `*.jest.mjs` file pattern
-2. **DO NOT create new Mocha tests** - only maintain existing ones
-3. **When modifying existing tests**, consider migrating to Jest if time permits
-4. **Both test suites must pass** before merging (`npm run test:all`)
-5. **Jest tests coexist with Mocha tests** in the same directories
-
-**Test Execution:**
-```bash
-# Run Mocha tests (legacy)
-npm test
-
-# Run Jest tests (new)
-npm run test:jest
-
-# Run both test suites (required for CI/CD)
-npm run test:all
-```
-
-### 5.5 Writing Good Tests
-
-**DO**:
-- Test one thing per test
-- Use descriptive test names
-- Test edge cases and error conditions
-- Make tests deterministic
-- Keep tests fast
-- Use property-based testing for core logic
-- **Write all new tests in Jest** (not Mocha)
-
-**DON'T**:
-- Test implementation details
-- Create flaky tests
-- Use real AWS services (mock them)
-- Make tests dependent on each other
-- Skip tests without good reason
-- **Create new Mocha tests** (migration in progress)
-
-**Example Test Structure (Jest - Use This for New Tests):**
-
-```javascript
-import { describe, it, expect } from '@jest/globals';
-import { Cache } from '../src/lib/dao-cache.js';
-
-describe('Cache', () => {
-    describe('generateIdHash()', () => {
-        it('should generate consistent hash for same input', () => {
-            const conn = { host: 'example.com', path: '/api' };
-            const hash1 = Cache.generateIdHash(conn);
-            const hash2 = Cache.generateIdHash(conn);
-            expect(hash1).toBe(hash2);
-        });
-
-        it('should generate different hashes for different inputs', () => {
-            const conn1 = { host: 'example.com', path: '/api' };
-            const conn2 = { host: 'example.com', path: '/api2' };
-            const hash1 = Cache.generateIdHash(conn1);
-            const hash2 = Cache.generateIdHash(conn2);
-            expect(hash1).not.toBe(hash2);
-        });
-
-        it('should handle null input gracefully', () => {
-            expect(() => Cache.generateIdHash(null)).not.toThrow();
-        });
-    });
-});
-```
-
-**Legacy Test Structure (Mocha - Maintain Only, Don't Create New):**
-
-```javascript
-import { expect } from 'chai';
-import { Cache } from '../src/lib/dao-cache.js';
-
-describe('Cache', () => {
-    describe('generateIdHash()', () => {
-        it('should generate consistent hash for same input', () => {
-            const conn = { host: 'example.com', path: '/api' };
-            const hash1 = Cache.generateIdHash(conn);
-            const hash2 = Cache.generateIdHash(conn);
-            expect(hash1).to.equal(hash2);
-        });
-    });
-});
-```
-
-## 6. Kiro Steering Documents
-
-This repository uses Kiro for AI-assisted development. Steering documents provide additional context and rules.
-
-**Location**: `.kiro/steering/`
-
-**Available Steering Documents**:
-
-1. **spec-naming-convention.md**: Spec directory naming rules
-   - Format: `{version}-{feature-name}`
-   - Version from package.json with dots replaced by hyphens
-   - Example: `.kiro/specs/1-3-6-in-memory-cache/`
-
-2. **documentation-standards.md**: Complete documentation standards
-   - JSDoc requirements and templates
-   - Documentation update process
-   - Quality standards and validation
-   - Common pitfalls and solutions
-
-**CRITICAL**: Always follow steering document rules. They take precedence over general guidelines.
-
-## 7. Spec-Driven Development
-
-This project uses spec-driven development for new features.
-
-### 7.1 Spec Structure
-
-Specs are located in `.kiro/specs/{version}-{feature-name}/`:
-
-- `requirements.md`: User stories and acceptance criteria
-- `design.md`: Technical design and correctness properties
-- `tasks.md`: Implementation task list
-
-### 7.2 Spec Workflow
-
-1. **Requirements**: Define what needs to be built
-2. **Design**: Define how it will be built
-3. **Tasks**: Break down into implementable tasks
-4. **Implementation**: Execute tasks one at a time
-5. **Testing**: Validate against correctness properties
-
-### 7.3 Property-Based Testing in Specs
-
-Specs include correctness properties that must be validated:
-
-- Properties are formal specifications of behavior
-- Properties are tested using property-based testing
-- Properties must pass before feature is complete
-- Properties are linked to requirements
-
-**Example Property:**
-
-```
-Property 1: Cache Hit Consistency
-For all valid cache keys and data:
-  If data is written to cache with key K,
-  Then reading from cache with key K returns the same data
-  Until the expiration time is reached
-```
-
-## 8. Common Patterns and Anti-Patterns
-
-### 8.1 Good Patterns
-
-**Initialization Pattern:**
-```javascript
-class MyClass {
-    static #initialized = false;
-    static #config = null;
-
-    static init(config) {
-        if (this.#initialized) {
-            tools.DebugAndLog.warn("Already initialized");
-            return;
-        }
-        this.#config = config;
-        this.#initialized = true;
-    }
-}
-```
-
-**Error Handling Pattern:**
-```javascript
-static async operation() {
-    return new Promise(async (resolve) => {
-        try {
-            const result = await doSomething();
-            resolve(result);
-        } catch (error) {
-            tools.DebugAndLog.error(`Operation failed: ${error?.message}`, error?.stack);
-            resolve(defaultValue);
-        }
-    });
-}
-```
-
-**Configuration Pattern:**
-```javascript
-static init(parameters) {
-    this.#setting = parameters.setting || 
-        process.env.ENV_VAR || 
-        defaultValue;
-}
-```
-
-### 8.2 Anti-Patterns to Avoid
-
-**DON'T: Break backwards compatibility**
-```javascript
-// BAD: Changed parameter order
-static write(body, idHash) { } // Was: write(idHash, body)
-
-// GOOD: Add new optional parameter at end
-static write(idHash, body, options = {}) { }
-```
-
-**DON'T: Ignore errors**
-```javascript
-// BAD: Silent failure
-try {
-    await operation();
-} catch (error) {
-    // Nothing
-}
-
-// GOOD: Log and handle
-try {
-    await operation();
-} catch (error) {
-    tools.DebugAndLog.error(`Failed: ${error?.message}`, error?.stack);
-    return defaultValue;
-}
-```
-
-**DON'T: Create god classes**
-```javascript
-// BAD: Too many responsibilities
-class CacheAndEndpointAndLogging {
-    cache() { }
-    request() { }
-    log() { }
-}
-
-// GOOD: Separate concerns
-class Cache { }
-class Endpoint { }
-class Logger { }
-```
-
-**DON'T: Duplicate functionality**
-```javascript
-// BAD: Reimplementing existing functionality
-function myHash(data) {
-    // Custom hash implementation
-}
-
-// GOOD: Use existing functionality
-const hash = tools.hashThisData(data);
-```
-
-## 9. Deployment and Versioning
-
-### 9.1 Release Process
-
-1. Update version in `package.json`
-2. Update `CHANGELOG.md` with changes
-3. Run all tests: `npm test`
-4. Run documentation validation
-5. Commit changes
-6. Create git tag: `git tag v1.3.6`
-7. Push to npm: `npm publish`
-
-### 9.2 Changelog Format
-
-Follow existing CHANGELOG.md format:
-
-```markdown
-## [1.3.6] - 2026-02-01
-
-### Added
-- New feature description
-
-### Changed
-- Changed behavior description
-
-### Fixed
-- Bug fix description
-
-### Deprecated
-- Deprecated feature with migration path
-```
-
-### 9.3 Breaking Changes
-
-**CRITICAL**: Breaking changes require major version bump.
-
-Breaking changes include:
-- Removed exports
-- Changed function signatures
-- Changed default behaviors
-- Removed or renamed parameters
-- Changed return types
-- Changed error behaviors
-
-**Process for breaking changes:**
-1. Discuss with user first
-2. Create migration guide
-3. Update major version
-4. Document in CHANGELOG.md
-5. Update all documentation
-6. Update all examples
-
-## 10. AWS Integration
-
-### 10.1 AWS Services Used
-
-- **S3**: Large object storage for cache
-- **DynamoDB**: Metadata and small object storage
-- **SSM Parameter Store**: Configuration and secrets
-- **Lambda**: Execution environment (Node.js >= 20.0.0)
-
-### 10.2 AWS SDK Usage
-
-**CRITICAL**: Use AWS SDK v3 only. Do not mix v2 and v3.
-
-```javascript
-// GOOD: Use tools.AWS wrapper
-const result = await tools.AWS.s3.get(params);
-const item = await tools.AWS.dynamo.get(params);
-
-// BAD: Direct SDK usage
-const s3 = new S3Client();
-```
-
-### 10.3 IAM Permissions Required
-
-Lambda execution role needs:
-- S3: GetObject, PutObject
-- DynamoDB: GetItem, PutItem
-- SSM: GetParameter, GetParameters, GetParametersByPath
-
-## 11. Performance Optimization
-
-### 11.1 Lambda Memory Allocation
-
-Recommended: 1024MB - 2048MB
-Minimum: 512MB
-
-See: `docs/lambda-optimization/README.md`
-
-### 11.2 Cache Strategy
-
-- Use in-memory cache for hot data
-- Use DynamoDB for small items (< 10KB)
-- Use S3 for large items (> 10KB)
-- Set appropriate expiration times
-- Use interval-based expiration for predictable patterns
-
-### 11.3 Optimization Techniques
-
-- Minimize JSON.stringify() calls
-- Use Promise.all() for parallel operations
-- Reuse connections and clients
-- Cache expensive computations
-- Use appropriate data structures
-
-## 12. Troubleshooting
-
-### 12.1 Common Issues
-
-**Issue**: Tests failing after changes
-- **Solution**: Check if backwards compatibility broken
-- **Solution**: Verify test expectations are correct
-- **Solution**: Check for race conditions
-
-**Issue**: Documentation validation failing
-- **Solution**: Ensure JSDoc matches implementation
-- **Solution**: Check parameter names match exactly
-- **Solution**: Verify examples are executable
-
-**Issue**: Performance degradation
-- **Solution**: Check for unnecessary AWS calls
-- **Solution**: Verify in-memory cache is enabled
-- **Solution**: Check Lambda memory allocation
-
-### 12.2 Debugging
-
-Use `tools.DebugAndLog` for debugging:
-
-```javascript
-tools.DebugAndLog.debug('Debug message', data);
-tools.DebugAndLog.info('Info message');
-tools.DebugAndLog.warn('Warning message');
-tools.DebugAndLog.error('Error message', error?.stack);
-```
-
-Set log level via environment variable:
-```bash
-DEBUG_MODE=true
-```
-
-## 13. Quick Reference
-
-### 13.1 Before Making Changes
-
-- [ ] Read this AI_CONTEXT.md document
-- [ ] Review steering documents in `.kiro/steering/`
-- [ ] Check existing tests for expected behavior
-- [ ] Search codebase for similar functionality
-- [ ] Verify backwards compatibility impact
-
-### 13.2 Before Committing
-
-- [ ] All tests pass: `npm test`
-- [ ] Documentation updated and validated
-- [ ] CHANGELOG.md updated
-- [ ] No breaking changes (or properly versioned)
-- [ ] Code follows style guidelines
-- [ ] Error handling is proper
-- [ ] Performance impact considered
-
-### 13.3 Key Commands
-
-```bash
-# Run all tests
-npm test
-
-# Run specific test suite
-npm run test:cache
-npm run test:endpoint
-npm run test:utils
-
-# Run documentation validation
-npm test -- test/documentation/
-
-# Run documentation audit
-node scripts/audit-documentation.mjs
-```
-
-### 13.4 Key Files
-
-- `src/index.js`: Main entry point
-- `src/lib/dao-cache.js`: Cache module
-- `src/lib/dao-endpoint.js`: Endpoint module
-- `src/lib/tools/index.js`: Tools module
-- `package.json`: Version and dependencies
-- `CHANGELOG.md`: Version history
-- `.kiro/steering/`: Steering documents
-
-## 14. Getting Help
-
-### 14.1 Documentation
-
-- README.md: Package overview and quick start
-- docs/: Detailed documentation
-- test/: Test examples showing usage
-- .kiro/steering/: Development guidelines
-
-### 14.2 Resources
-
-- GitHub Issues: https://github.com/63Klabs/cache-data/issues
-- NPM Package: https://www.npmjs.com/package/@63klabs/cache-data
-- Atlantis Platform: https://github.com/63klabs/atlantis-tutorials
-
----
-
-## Summary
-
-**Remember the priorities:**
-
-1. **Backwards Compatibility**: Never break existing code
-2. **Testing**: All changes must have tests
-3. **Documentation**: All public APIs must be documented
-4. **Separation of Concerns**: Keep modules and classes focused
-5. **Performance**: This runs in production at scale
-6. **Security**: Handle sensitive data properly
-
-**When in doubt:**
-- Check existing code for patterns
-- Review steering documents
-- Ask the user before making breaking changes
-- Write tests first
-- Document as you go
-
-This package is used in production by real applications. Quality and reliability are non-negotiable.