@63klabs/cache-data 1.3.7 → 1.3.9

package/AGENTS.md

@@ -0,0 +1,1107 @@
+# 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 Non-Public Class Organization
+
+**CRITICAL**: Not all classes should be exported in the public API. Internal implementation classes must be kept separate from user-facing APIs.
+
+#### Directory Structure for Classes
+
+- **`src/lib/tools/`**: Public API classes and utilities
+  - Classes exported in `src/lib/tools/index.js`
+  - User-facing functionality
+  - Examples: `DebugAndLog`, `Timer`, `Response`, `APIRequest`
+
+- **`src/lib/utils/`**: Internal implementation classes
+  - Classes NOT exported in public API
+  - Used internally by public classes
+  - Examples: `InMemoryCache`, `ValidationExecutor`, `ValidationMatcher`
+
+#### When to Use Each Directory
+
+**Use `src/lib/tools/` when:**
+- Class is part of the public API
+- Users need direct access to the class
+- Class is exported in `src/index.js` or `src/lib/tools/index.js`
+- Class provides user-facing functionality
+
+**Use `src/lib/utils/` when:**
+- Class is internal implementation detail
+- Class is only used by other classes in the package
+- Class should not be exposed to users
+- Class is a helper or utility for internal use
+
+#### Example: ValidationExecutor and ValidationMatcher
+
+These classes are internal to ClientRequest's validation system:
+
+```javascript
+// src/lib/utils/ValidationExecutor.class.js
+// Internal class - not exported in public API
+class ValidationExecutor {
+  static execute(validateFn, paramNames, paramValues) {
+    // Implementation
+  }
+}
+
+// src/lib/utils/ValidationMatcher.class.js  
+// Internal class - not exported in public API
+class ValidationMatcher {
+  constructor(paramValidations, httpMethod, resourcePath) {
+    // Implementation
+  }
+}
+
+// src/lib/tools/ClientRequest.class.js
+// Public class - uses internal classes
+const ValidationMatcher = require('../utils/ValidationMatcher.class');
+const ValidationExecutor = require('../utils/ValidationExecutor.class');
+
+class ClientRequest {
+  // Uses ValidationMatcher and ValidationExecutor internally
+}
+```
+
+#### Testing Internal Classes
+
+Internal classes can still be tested using direct imports in test files:
+
+```javascript
+// test/request/validation/unit/validation-executor-tests.jest.mjs
+const ValidationExecutorModule = await import('../../../../src/lib/utils/ValidationExecutor.class.js');
+const ValidationExecutor = ValidationExecutorModule.default;
+
+describe('ValidationExecutor', () => {
+  it('should execute validation correctly', () => {
+    // Test internal class
+  });
+});
+```
+
+#### Rules for AI Assistants
+
+When creating new classes:
+
+1. **Determine visibility**: Is this class part of the public API?
+2. **Choose directory**: 
+   - Public API → `src/lib/tools/`
+   - Internal implementation → `src/lib/utils/`
+3. **Update exports**: Only export public classes in `src/lib/tools/index.js`
+4. **Document clearly**: Mark internal classes with `@private` JSDoc tag
+5. **Test appropriately**: Internal classes can be tested directly
+
+**DO NOT**:
+- Export internal classes in public API
+- Place public API classes in `src/lib/utils/`
+- Mix concerns between directories
+- Change class location without updating all imports
+
+### 3.5 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.