holosphere 2.0.0-alpha0 → 2.0.0-alpha2

package/docs/contracts/api-interface.md

@@ -0,0 +1,793 @@
+# HoloSphere API Contract
+
+**Version**: 1.0.0
+**Date**: 2025-10-07
+**Format**: JavaScript Library API (not REST/HTTP)
+
+## Overview
+This document defines the public API surface for HoloSphere. All methods are async (return Promises) and follow the constitutional design patterns.
+
+---
+
+## 1. Core Initialization
+
+### `new HoloSphere(config)`
+Creates a new HoloSphere instance.
+
+**Parameters**:
+```typescript
+config?: {
+  appName: string;              // Default: 'holosphere'
+  backend?: 'nostr' | 'gundb' | 'activitypub';  // Default: 'nostr'
+  logLevel?: 'ERROR' | 'WARN' | 'INFO' | 'DEBUG';  // Default: 'WARN'
+
+  // Nostr-specific (default backend)
+  relays?: string[];            // Nostr relay URLs
+  privateKey?: string;          // Hex-encoded private key
+
+  // GunDB-specific
+  gundb?: {
+    peers?: string[];           // GunDB peer relay URLs
+    radisk?: boolean;           // Enable radisk (default: true)
+    localStorage?: boolean;     // Enable localStorage (default: true)
+  };
+
+  // ActivityPub-specific
+  activitypub?: {
+    serverUrl: string;          // ActivityPub server URL (required)
+    apiKey?: string;            // Server API key for authentication
+  };
+
+  // Common options
+  persistence?: boolean;        // Enable local persistence (default: true)
+  dataDir?: string;             // Custom data directory path
+}
+```
+
+**Returns**: `HoloSphere` instance
+
+**Example**:
+```javascript
+// Default (Nostr backend)
+const hs = new HoloSphere({
+  appName: 'myapp',
+  relays: ['wss://relay.damus.io'],
+  logLevel: 'INFO'
+});
+
+// GunDB backend
+const hsGun = new HoloSphere({
+  appName: 'myapp',
+  backend: 'gundb',
+  gundb: {
+    peers: ['https://gun.example.com/gun'],
+    radisk: true
+  }
+});
+
+// ActivityPub backend (requires running server)
+const hsAP = new HoloSphere({
+  appName: 'myapp',
+  backend: 'activitypub',
+  activitypub: {
+    serverUrl: 'http://localhost:3000',
+    apiKey: 'your-api-key'
+  }
+});
+```
+
+**Errors**:
+- Throws `TypeError` if config is invalid
+- Throws `Error` if GunDB initialization fails
+
+**Contract Test**: Create instance with default and custom configs
+
+---
+
+## 2. Spatial Operations
+
+### `holosphere.toHolon(lat, lng, resolution)`
+Convert geographic coordinates to H3 holon ID.
+
+**Parameters**:
+- `lat: number` - Latitude (-90 to 90)
+- `lng: number` - Longitude (-180 to 180)
+- `resolution: number` - H3 resolution (0-15)
+
+**Returns**: `Promise<string>` - H3 cell ID
+
+**Example**:
+```javascript
+const holonId = await hs.toHolon(37.7749, -122.4194, 9);
+// => "8928342e20fffff"
+```
+
+**Errors**:
+- Throws `RangeError` if lat/lng out of bounds
+- Throws `RangeError` if resolution not 0-15
+
+**Contract Test**: Valid coords → valid H3, invalid coords → error
+
+---
+
+### `holosphere.getParents(holonId, maxResolution?)`
+Get all parent holons up the hierarchy.
+
+**Parameters**:
+- `holonId: string` - H3 cell ID
+- `maxResolution?: number` - Stop at this resolution (default: 0)
+
+**Returns**: `Promise<string[]>` - Array of parent H3 IDs (ascending hierarchy)
+
+**Example**:
+```javascript
+const parents = await hs.getParents("8928342e20fffff", 5);
+// => ["8828342e2ffffff", "8728342e2ffffff", ...]
+```
+
+**Errors**:
+- Throws `Error` if holonId is invalid H3 format
+
+**Contract Test**: Valid H3 → parent array, invalid H3 → error
+
+---
+
+### `holosphere.getChildren(holonId)`
+Get all child holons at next resolution level.
+
+**Parameters**:
+- `holonId: string` - H3 cell ID
+
+**Returns**: `Promise<string[]>` - Array of child H3 IDs (7 children per hexagon)
+
+**Example**:
+```javascript
+const children = await hs.getChildren("8828342e2ffffff");
+// => ["8928342e20fffff", "8928342e21fffff", ...]
+```
+
+**Errors**:
+- Throws `Error` if holonId is invalid or already at resolution 15
+
+**Contract Test**: Valid H3 → 7 children, res 15 → error
+
+---
+
+## 3. Data Operations
+
+### `holosphere.write(holonId, lensName, data, options?)`
+Write data to a holon/lens.
+
+**Parameters**:
+- `holonId: string` - H3 cell ID or noospheric URI
+- `lensName: string` - Lens name
+- `data: object` - Data to write (must include `id` or will be auto-generated)
+- `options?: object` - Optional configuration
+
+**Options**:
+```typescript
+{
+  validate?: boolean;        // Validate against schema (default: true if schema exists)
+  strict?: boolean;          // Strict validation mode (default: false)
+  capability?: string;       // Capability token for authorization
+}
+```
+
+**Returns**: `Promise<boolean>` - True if write succeeded
+
+**Example**:
+```javascript
+const success = await hs.write(
+  "8928342e20fffff",
+  "temperature",
+  { id: "sensor-1", value: 72.5, unit: "F" }
+);
+// => true
+```
+
+**Errors**:
+- Throws `ValidationError` if strict mode enabled and data invalid
+- Throws `AuthorizationError` if capability token invalid
+- Returns `false` if write fails (Gun error)
+
+**Contract Test**: Valid data → true, invalid data (strict) → ValidationError
+
+---
+
+### `holosphere.read(holonId, lensName, dataId?)`
+Read data from a holon/lens.
+
+**Parameters**:
+- `holonId: string` - H3 cell ID or noospheric URI
+- `lensName: string` - Lens name
+- `dataId?: string` - Optional: specific data item ID
+
+**Returns**: `Promise<object | object[] | null>`
+- If `dataId` provided: single object or null
+- If `dataId` omitted: array of all objects in lens
+
+**Example**:
+```javascript
+// Read specific item
+const temp = await hs.read("8928342e20fffff", "temperature", "sensor-1");
+// => { id: "sensor-1", value: 72.5, unit: "F" }
+
+// Read all items in lens
+const allTemps = await hs.read("8928342e20fffff", "temperature");
+// => [{ id: "sensor-1", ... }, { id: "sensor-2", ... }]
+```
+
+**Errors**:
+- Returns `null` if data not found
+- Throws `Error` if holonId or lensName invalid
+
+**Contract Test**: Existing data → object, non-existent → null
+
+---
+
+### `holosphere.delete(holonId, lensName, dataId, options?)`
+Delete data from a holon/lens.
+
+**Parameters**:
+- `holonId: string` - H3 cell ID or noospheric URI
+- `lensName: string` - Lens name
+- `dataId: string` - Data item ID
+- `options?: object` - Optional configuration
+
+**Options**:
+```typescript
+{
+  capability?: string;       // Required if deleting data created by others
+}
+```
+
+**Returns**: `Promise<boolean>` - True if delete succeeded
+
+**Example**:
+```javascript
+const deleted = await hs.delete("8928342e20fffff", "temperature", "sensor-1");
+// => true
+```
+
+**Errors**:
+- Throws `AuthorizationError` if deleting others' data without capability token
+- Returns `false` if delete fails
+
+**Contract Test**: Own data → true, others' data without token → AuthorizationError
+
+---
+
+### `holosphere.update(holonId, lensName, dataId, updates, options?)`
+Update existing data (merge).
+
+**Parameters**:
+- `holonId: string`
+- `lensName: string`
+- `dataId: string`
+- `updates: object` - Fields to merge
+- `options?: object` - Same as write()
+
+**Returns**: `Promise<boolean>`
+
+**Example**:
+```javascript
+await hs.update("8928342e20fffff", "temperature", "sensor-1", { value: 73.0 });
+```
+
+**Errors**: Same as write()
+
+**Contract Test**: Valid updates → true, non-existent item → false
+
+---
+
+## 4. Schema Operations
+
+### `holosphere.setSchema(lensName, schemaUri, strict?)`
+Define validation schema for a lens.
+
+**Parameters**:
+- `lensName: string`
+- `schemaUri: string` - URI pointing to JSON Schema 2019
+- `strict?: boolean` - Validation mode (default: false)
+
+**Returns**: `Promise<void>`
+
+**Example**:
+```javascript
+await hs.setSchema(
+  "temperature",
+  "https://schema.example.com/temperature.json",
+  true  // Strict mode
+);
+```
+
+**Errors**:
+- Throws `Error` if schema fetch fails
+- Throws `ValidationError` if schema is invalid JSON Schema format
+
+**Contract Test**: Valid schema → no error, invalid schema → ValidationError
+
+---
+
+### `holosphere.getSchema(lensName)`
+Retrieve schema for a lens.
+
+**Parameters**:
+- `lensName: string`
+
+**Returns**: `Promise<object | null>` - JSON Schema object or null if not set
+
+**Example**:
+```javascript
+const schema = await hs.getSchema("temperature");
+// => { type: "object", properties: { ... } }
+```
+
+**Errors**: None (returns null if not found)
+
+**Contract Test**: Existing schema → object, non-existent → null
+
+---
+
+### `holosphere.clearSchema(lensName)`
+Remove schema from a lens.
+
+**Parameters**:
+- `lensName: string`
+
+**Returns**: `Promise<void>`
+
+**Example**:
+```javascript
+await hs.clearSchema("temperature");
+```
+
+**Errors**: None (idempotent)
+
+**Contract Test**: After clear, getSchema returns null
+
+---
+
+## 5. Federation Operations
+
+### `holosphere.federate(sourceHolon, targetHolon, lensName, options?)`
+Establish federation between two holons.
+
+**Parameters**:
+- `sourceHolon: string` - Source holon ID
+- `targetHolon: string` - Target holon ID
+- `lensName: string` - Lens to federate
+- `options?: object`
+
+**Options**:
+```typescript
+{
+  direction?: 'inbound' | 'outbound' | 'bidirectional';  // Default: 'outbound'
+  mode?: 'reference' | 'copy';                            // Default: 'reference'
+  filter?: (data: object) => boolean;                     // Optional data filter
+}
+```
+
+**Returns**: `Promise<boolean>` - True if federation established
+
+**Example**:
+```javascript
+// Geographic → Noospheric federation
+await hs.federate(
+  "8928342e20fffff",
+  "nostr://topic/climate",
+  "temperature",
+  { direction: 'bidirectional' }
+);
+```
+
+**Errors**:
+- Throws `Error` if source === target
+- Returns `false` if federation setup fails
+
+**Contract Test**: Valid holons → true, self-federation → error
+
+---
+
+### `holosphere.getFederatedData(holonId, lensName, options?)`
+Query data including federated sources.
+
+**Parameters**:
+- `holonId: string`
+- `lensName: string`
+- `options?: object`
+
+**Options**:
+```typescript
+{
+  resolveHolograms?: boolean;  // Resolve references (default: true)
+  deduplicate?: boolean;       // Remove duplicates (default: true)
+}
+```
+
+**Returns**: `Promise<object[]>` - Combined local + federated data
+
+**Example**:
+```javascript
+const allData = await hs.getFederatedData("8928342e20fffff", "temperature");
+// => [{ id: "local-1", ... }, { id: "federated-1", _meta: { source: "..." } }]
+```
+
+**Errors**: None (returns empty array if no data)
+
+**Contract Test**: Federated holon → includes remote data, non-federated → local only
+
+---
+
+### `holosphere.unfederate(sourceHolon, targetHolon, lensName)`
+Remove federation relationship.
+
+**Parameters**:
+- `sourceHolon: string`
+- `targetHolon: string`
+- `lensName: string`
+
+**Returns**: `Promise<boolean>`
+
+**Example**:
+```javascript
+await hs.unfederate("8928342e20fffff", "nostr://topic/climate", "temperature");
+```
+
+**Errors**: None (idempotent)
+
+**Contract Test**: After unfederate, getFederatedData excludes remote data
+
+---
+
+## 6. Hierarchical Operations
+
+### `holosphere.upcast(holonId, lensName, dataId, options?)`
+Propagate data to parent holons.
+
+**Parameters**:
+- `holonId: string` - Source holon
+- `lensName: string`
+- `dataId: string`
+- `options?: object`
+
+**Options**:
+```typescript
+{
+  maxLevel?: number;           // Max parent levels (default: Infinity)
+  operation?: 'summarize' | 'aggregate' | 'concatenate';  // Default: 'concatenate'
+}
+```
+
+**Returns**: `Promise<boolean>`
+
+**Example**:
+```javascript
+await hs.upcast("8928342e20fffff", "events", "event-123", { maxLevel: 3 });
+```
+
+**Errors**:
+- Throws `Error` if holonId is not geographic (noospheric holons have no hierarchy)
+
+**Contract Test**: Valid upcast → data in parents, noospheric → error
+
+---
+
+## 7. Subscription Operations
+
+### `holosphere.subscribe(holonId, lensName, callback, options?)`
+Subscribe to real-time data changes.
+
+**Parameters**:
+- `holonId: string`
+- `lensName: string`
+- `callback: (data: object, key: string) => void`
+- `options?: object`
+
+**Options**:
+```typescript
+{
+  includeFederated?: boolean;  // Include federated data (default: false)
+  throttle?: number;           // Milliseconds between updates (default: 0)
+  filter?: (data: object) => boolean;
+}
+```
+
+**Returns**: `{ unsubscribe: () => void }` - Subscription object
+
+**Example**:
+```javascript
+const sub = hs.subscribe("8928342e20fffff", "temperature", (data, key) => {
+  console.log("Temperature updated:", data);
+});
+
+// Later...
+sub.unsubscribe();
+```
+
+**Errors**:
+- Throws `TypeError` if callback is not a function
+
+**Contract Test**: Subscription receives updates, unsubscribe stops updates
+
+---
+
+## 8. Cryptographic Operations
+
+### `holosphere.sign(content, privateKey)`
+Sign content with secp256k1.
+
+**Parameters**:
+- `content: object | string` - Content to sign
+- `privateKey: string` - Hex-encoded private key
+
+**Returns**: `Promise<string>` - Hex-encoded signature
+
+**Example**:
+```javascript
+const sig = await hs.sign({ message: "Hello" }, privateKey);
+```
+
+**Errors**:
+- Throws `Error` if private key is invalid
+- Lazy loads crypto module on first call
+
+**Contract Test**: Valid content → signature, invalid key → error
+
+---
+
+### `holosphere.verify(content, signature, publicKey)`
+Verify signature.
+
+**Parameters**:
+- `content: object | string`
+- `signature: string` - Hex-encoded signature
+- `publicKey: string` - Hex-encoded public key
+
+**Returns**: `Promise<boolean>` - True if signature valid
+
+**Example**:
+```javascript
+const isValid = await hs.verify({ message: "Hello" }, sig, pubkey);
+```
+
+**Errors**: None (returns false if invalid)
+
+**Contract Test**: Valid signature → true, tampered content → false
+
+---
+
+### `holosphere.issueCapability(permissions, scope, recipient, options?)`
+Issue capability token.
+
+**Parameters**:
+- `permissions: string[]` - e.g., ['read', 'write', 'delete']
+- `scope: { holonId?: string, lensName?: string }`
+- `recipient: string` - Public key
+- `options?: object`
+
+**Options**:
+```typescript
+{
+  expiresIn?: number;  // Milliseconds (default: 3600000 = 1 hour)
+  issuerKey?: string;  // Private key (default: use internal)
+}
+```
+
+**Returns**: `Promise<string>` - Capability token (signed JWT-like format)
+
+**Example**:
+```javascript
+const token = await hs.issueCapability(
+  ['read', 'write'],
+  { holonId: "8928342e20fffff", lensName: "temperature" },
+  recipientPubkey,
+  { expiresIn: 86400000 }  // 24 hours
+);
+```
+
+**Errors**:
+- Throws `Error` if issuer key invalid
+
+**Contract Test**: Valid params → token string, invalid key → error
+
+---
+
+### `holosphere.verifyCapability(token, requiredPermission, scope)`
+Verify capability token.
+
+**Parameters**:
+- `token: string`
+- `requiredPermission: string` - e.g., 'delete'
+- `scope: { holonId: string, lensName: string }`
+
+**Returns**: `Promise<boolean>` - True if token grants permission
+
+**Example**:
+```javascript
+const canDelete = await hs.verifyCapability(
+  token,
+  'delete',
+  { holonId: "8928342e20fffff", lensName: "temperature" }
+);
+```
+
+**Errors**: None (returns false if invalid/expired)
+
+**Contract Test**: Valid token → true, expired token → false
+
+---
+
+## 9. Social Protocol Operations
+
+### `holosphere.publishNostr(event, holonId, lensName?)`
+Publish Nostr event to holon.
+
+**Parameters**:
+- `event: object` - Nostr event (NIP-01 format)
+- `holonId: string`
+- `lensName?: string` - Default: 'social'
+
+**Returns**: `Promise<boolean>`
+
+**Example**:
+```javascript
+const nostrEvent = {
+  kind: 1,
+  content: "Hello from HoloSphere!",
+  tags: [["t", "holosphere"]],
+  // ... (will be signed automatically)
+};
+
+await hs.publishNostr(nostrEvent, "8928342e20fffff");
+```
+
+**Errors**:
+- Throws `ValidationError` if event format invalid
+- Throws `Error` if signature verification fails
+
+**Contract Test**: Valid event → true, invalid format → ValidationError
+
+---
+
+### `holosphere.publishActivityPub(object, holonId, lensName?)`
+Publish ActivityPub object to holon.
+
+**Parameters**:
+- `object: object` - ActivityPub object
+- `holonId: string`
+- `lensName?: string` - Default: 'social'
+
+**Returns**: `Promise<boolean>`
+
+**Example**:
+```javascript
+const apObject = {
+  "@context": "https://www.w3.org/ns/activitystreams",
+  type: "Note",
+  content: "Hello from HoloSphere!",
+  // ... (will be signed automatically)
+};
+
+await hs.publishActivityPub(apObject, "nostr://topic/general");
+```
+
+**Errors**: Same as publishNostr
+
+**Contract Test**: Valid object → true, invalid format → ValidationError
+
+---
+
+### `holosphere.querySocial(holonId, options?)`
+Query social content.
+
+**Parameters**:
+- `holonId: string`
+- `options?: object`
+
+**Options**:
+```typescript
+{
+  protocol?: 'nostr' | 'activitypub' | 'all';  // Default: 'all'
+  accessLevel?: 'public' | 'protected' | 'private' | 'all';  // Default: 'public'
+  lensName?: string;  // Default: 'social'
+}
+```
+
+**Returns**: `Promise<object[]>` - Array of social content objects
+
+**Example**:
+```javascript
+const posts = await hs.querySocial("8928342e20fffff", { protocol: 'nostr' });
+```
+
+**Errors**: None (returns empty array if no content)
+
+**Contract Test**: With content → array, empty → [], filter works
+
+---
+
+## 10. Utility Operations
+
+### `holosphere.isValidH3(holonId)`
+Validate H3 format.
+
+**Parameters**:
+- `holonId: string`
+
+**Returns**: `boolean`
+
+**Example**:
+```javascript
+hs.isValidH3("8928342e20fffff");  // => true
+hs.isValidH3("invalid");          // => false
+```
+
+**Errors**: None
+
+**Contract Test**: Valid H3 → true, invalid → false
+
+---
+
+### `holosphere.metrics()`
+Get usage metrics.
+
+**Parameters**: None
+
+**Returns**: `object` - Metrics snapshot
+
+**Example**:
+```javascript
+const metrics = hs.metrics();
+// => {
+//   writes: 1523,
+//   reads: 8942,
+//   subscriptions: 12,
+//   federations: 3,
+//   avgWriteTime: 15.3,  // ms
+//   avgReadTime: 8.7     // ms
+// }
+```
+
+**Errors**: None
+
+**Contract Test**: Returns object with expected properties
+
+---
+
+## Error Types
+
+```typescript
+class ValidationError extends Error {
+  constructor(message: string, errors: object[]);
+  errors: object[];  // Ajv validation errors
+}
+
+class AuthorizationError extends Error {
+  constructor(message: string, requiredPermission?: string);
+  requiredPermission?: string;
+}
+
+class HolosphereError extends Error {
+  constructor(message: string, code: string);
+  code: string;  // Error code for programmatic handling
+}
+```
+
+---
+
+## Contract Test Summary
+
+Each API method must have:
+1. **Success case test**: Valid inputs → expected output
+2. **Error case test**: Invalid inputs → expected error
+3. **Edge case test**: Boundary conditions (empty data, null values, etc.)
+4. **Integration test**: Cross-module interaction (e.g., write → read → update → delete)
+
+**Coverage Target**: 100% of public API methods
+
+---
+
+## Next Steps
+✅ API contract complete with all methods, parameters, and error handling
+➡️ Generate quickstart.md with user story scenarios