feat: implement Phase 6.5 - Advanced CID API with comprehensive test suite

  Adds optional CID-aware API for advanced users without affecting path-based API simplicity:

  - CID utilities (formatCID, parseCID, verifyCID, cidToString) with 38 tests
  - FS5Advanced class (pathToCID, cidToPath, getByCID, putByCID, putWithCID) with 36 tests
  - Advanced export package (s5/advanced) separate from main API
  - Bundle analysis: 59.53 KB compressed (well under 450 KB target)
  - Total: 74 tests passing, grant compliant (60.09 KB full bundle)

Author: Developer

docs/BUNDLE_ANALYSIS.md

@@ -1,6 +1,6 @@
 # S5.js Bundle Analysis Report
 
-**Generated:** 2025-10-17T21:36:18.716Z
+**Generated:** 2025-10-17T22:26:16.143Z
 
 ## Executive Summary
 
@@ -12,6 +12,7 @@ This report analyzes bundle sizes for different entry points of the S5.js librar
 |--------|-----|------|--------|--------|
 | Core | 214.72 KB | 71.75 KB | 59.61 KB | ✅ Pass |
 | Media | 35.98 KB | 11.03 KB | 9.79 KB | ✅ Pass |
+| Advanced | 214.92 KB | 71.35 KB | 59.53 KB | ✅ Pass |
 | Full | 217.15 KB | 72.37 KB | 60.09 KB | ✅ Pass |
 
 ## Tree-Shaking Analysis
@@ -56,6 +57,21 @@ The modular export structure enables consumers to import only what they need:
 - Input files: 9
 - Output modules: 1
 
+### Advanced
+
+**Description:** Advanced CID-aware API with core functionality
+
+**Entry Point:** `dist/src/exports/advanced.js`
+
+**Sizes:**
+- Raw: 214.92 KB
+- Gzipped: 71.35 KB (33.2% of raw)
+- Brotli: 59.53 KB (27.7% of raw)
+
+**Metadata:**
+- Input files: 295
+- Output modules: 1
+
 ### Full
 
 **Description:** Complete SDK with all features
@@ -112,6 +128,7 @@ The library uses a modular export structure with separate entry points:
 1. **Main export** (`s5`): Full SDK with all features
 2. **Core export** (`s5/core`): File system operations only
 3. **Media export** (`s5/media`): Media processing with lazy loading
+4. **Advanced export** (`s5/advanced`): CID-aware API for power users
 
 ### Lazy Loading
 

docs/IMPLEMENTATION.md

@@ -332,6 +332,59 @@
   - [x] Verify bundle size ≤ 700KB compressed (60.09 KB brotli - 10x under limit!) ✅
   - [x] Create bundle analysis report (docs/BUNDLE_ANALYSIS.md, bundle-analysis.json)
 
+### Phase 6.5: Advanced CID API (Optional Enhancement)
+
+**Goal**: Provide CID-level access for advanced developers without affecting path-based API simplicity
+
+- [x] **6.5.1 Test Suite First (TDD)** ✅ COMPLETE
+  - [x] Create test/fs/fs5-advanced.test.ts (~40 tests)
+  - [x] Write tests for CID extraction (pathToCID)
+  - [x] Write tests for CID lookup (cidToPath)
+  - [x] Write tests for direct CID operations (getByCID, putByCID)
+  - [x] Write tests for combined operations (putWithCID)
+  - [x] Create test/fs/cid-utils.test.ts (~50 tests)
+  - [x] Write tests for CID utilities (format, parse, verify)
+
+- [x] **6.5.2 CID Utilities** ✅ COMPLETE
+  - [x] Create src/fs/cid-utils.ts
+  - [x] Implement formatCID(cid, encoding) - multibase formatting
+  - [x] Implement parseCID(cidString) - parse various formats
+  - [x] Implement verifyCID(cid, data) - verify CID matches data
+  - [x] Implement cidToString(cid) - human-readable format
+  - [x] Add comprehensive unit tests (38/38 tests passing)
+
+- [x] **6.5.3 FS5Advanced Class** ✅ COMPLETE
+  - [x] Create src/fs/fs5-advanced.ts
+  - [x] Implement constructor(fs5: FS5)
+  - [x] Implement async pathToCID(path: string): Promise<Uint8Array>
+  - [x] Implement async cidToPath(cid: Uint8Array): Promise<string | null>
+  - [x] Implement async getByCID(cid: Uint8Array): Promise<any>
+  - [x] Implement async putByCID(data: any): Promise<Uint8Array>
+  - [x] Implement async putWithCID(path: string, data: any, options?): Promise<{ path: string, cid: Uint8Array }>
+  - [x] Implement async getMetadataWithCID(path: string): Promise<{ metadata: any, cid: Uint8Array }>
+  - [x] All 36 tests passing
+
+- [x] **6.5.4 Advanced Export Package** ✅ COMPLETE
+  - [x] Create src/exports/advanced.ts
+  - [x] Export FS5Advanced class
+  - [x] Export CID utility functions
+  - [x] Export FileRef, DirRef, DirLink types
+  - [x] Export BlobLocation types
+  - [x] Add to package.json exports: `"./advanced": "./dist/src/exports/advanced.js"`
+
+- [x] **6.5.5 Bundle Verification** ✅ COMPLETE
+  - [x] Run bundle analysis with advanced export
+  - [x] Verify tree-shaking works (advanced similar to core)
+  - [x] Advanced export is 59.53 KB compressed (similar to core)
+  - [x] Update BUNDLE_ANALYSIS.md with advanced bundle stats
+
+- [ ] **6.5.6 Documentation**
+  - [ ] Add Advanced API section to docs/API.md
+  - [ ] Create examples for CID operations
+  - [ ] Document when to use advanced vs. path-based API
+  - [ ] Add JSDoc comments to all public methods
+  - [ ] Update README with advanced import example
+
 ### Phase 7: Testing & Performance (Grant Month 7)
 
 - [ ] **7.1 Comprehensive Test Suite**

docs/bundle-analysis.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2025-10-17T21:36:18.718Z",
+  "timestamp": "2025-10-17T22:26:16.144Z",
   "bundles": [
     {
       "name": "Core",
@@ -29,6 +29,20 @@
         "modules": 1
       }
     },
+    {
+      "name": "Advanced",
+      "description": "Advanced CID-aware API with core functionality",
+      "entryPoint": "dist/src/exports/advanced.js",
+      "sizes": {
+        "raw": 220078,
+        "gzipped": 73067,
+        "brotli": 60954
+      },
+      "metadata": {
+        "inputs": 295,
+        "modules": 1
+      }
+    },
     {
       "name": "Full",
       "description": "Complete SDK with all features",

package.json

@@ -23,6 +23,11 @@
       "import": "./dist/src/exports/media.js",
       "default": "./dist/src/exports/media.js"
     },
+    "./advanced": {
+      "types": "./dist/src/exports/advanced.d.ts",
+      "import": "./dist/src/exports/advanced.js",
+      "default": "./dist/src/exports/advanced.js"
+    },
     "./dist/*": "./dist/*"
   },
   "scripts": {

scripts/analyze-bundle.js

@@ -45,6 +45,12 @@ const bundles = [
     description: 'Media processing modules only',
     expectedMaxSizeKB: 300, // Media processing
   },
+  {
+    name: 'Advanced',
+    entryPoint: 'dist/src/exports/advanced.js',
+    description: 'Advanced CID-aware API with core functionality',
+    expectedMaxSizeKB: 450, // Core + CID utilities
+  },
   {
     name: 'Full',
     entryPoint: 'dist/src/index.js',
@@ -315,6 +321,7 @@ The library uses a modular export structure with separate entry points:
 1. **Main export** (\`s5\`): Full SDK with all features
 2. **Core export** (\`s5/core\`): File system operations only
 3. **Media export** (\`s5/media\`): Media processing with lazy loading
+4. **Advanced export** (\`s5/advanced\`): CID-aware API for power users
 
 ### Lazy Loading
 

src/exports/advanced.ts

@@ -0,0 +1,61 @@
+/**
+ * Advanced S5.js API - CID-aware operations for power users
+ *
+ * This module provides low-level CID (Content Identifier) operations for advanced
+ * developers who need content-addressed storage capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { S5 } from 's5';
+ * import { FS5Advanced, formatCID, parseCID } from 's5/advanced';
+ *
+ * const s5 = await S5.create();
+ * await s5.recoverIdentityFromSeedPhrase(seedPhrase);
+ *
+ * // Create advanced API instance
+ * const advanced = new FS5Advanced(s5.fs);
+ *
+ * // Extract CID from path
+ * const cid = await advanced.pathToCID('home/data.txt');
+ *
+ * // Format CID for display
+ * const formatted = formatCID(cid, 'base32');
+ * console.log(formatted);
+ *
+ * // Parse CID from string
+ * const parsed = parseCID(formatted);
+ *
+ * // Retrieve data by CID
+ * const data = await advanced.getByCID(cid);
+ * ```
+ */
+
+// Core advanced API class
+export { FS5Advanced } from '../fs/fs5-advanced.js';
+export type { PutWithCIDResult, MetadataWithCIDResult } from '../fs/fs5-advanced.js';
+
+// CID utility functions
+export {
+  formatCID,
+  parseCID,
+  verifyCID,
+  cidToString,
+} from '../fs/cid-utils.js';
+
+// DirV1 types for advanced users
+export type {
+  DirV1,
+  FileRef,
+  DirRef,
+  DirLink,
+  BlobLocation,
+  HAMTShardingConfig,
+  PutOptions,
+  ListOptions,
+  GetOptions,
+  ListResult,
+} from '../fs/dirv1/types.js';
+
+// Re-export core S5 for convenience
+export { S5 } from '../s5.js';
+export { FS5 } from '../fs/fs5.js';