Merge remote-tracking branch 'upstream/main'

# Conflicts:
#	frontend/components/live/ActivityFeed.tsx

Author: mattleaverton

README.md

@@ -18,16 +18,18 @@ The fastest way to try CXDB is with the pre-built Docker image:
 # Run the server (binary protocol :9009, HTTP :9010)
 docker run -p 9009:9009 -p 9010:9010 -v $(pwd)/data:/data cxdb/cxdb:latest
 
-# Create a context and append a turn
-curl -X POST http://localhost:9010/v1/contexts
+# Create a context and append a turn (HTTP write path)
+curl -X POST http://localhost:9010/v1/contexts/create \
+  -H "Content-Type: application/json" \
+  -d '{"base_turn_id": "0"}'
 # => {"context_id": "1", "head_turn_id": "0", "head_depth": 0}
 
-curl -X POST http://localhost:9010/v1/contexts/1/turns \
+curl -X POST http://localhost:9010/v1/contexts/1/append \
   -H "Content-Type: application/json" \
   -d '{
     "type_id": "com.example.Message",
     "type_version": 1,
-    "payload": {"role": "user", "text": "Hello!"}
+    "data": {"role": "user", "text": "Hello!"}
   }'
 
 # View in the UI

docs/http-api.md

@@ -26,7 +26,9 @@ GET /v1/contexts
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `limit` | int | 100 | Max contexts to return |
-| `offset` | int | 0 | Pagination offset |
+| `tag` | string | - | Filter by exact client tag |
+| `include_provenance` | bool | false | Include provenance in each context |
+| `include_lineage` | bool | false | Include parent/root/children lineage summary |
 
 **Response:**
 
@@ -50,6 +52,13 @@ GET /v1/contexts
 GET /v1/contexts/:context_id
 ```
 
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `include_provenance` | bool | true | Include provenance block |
+| `include_lineage` | bool | true | Include lineage block with parent/root/children |
+
 **Response:**
 
 ```json
@@ -65,12 +74,33 @@ GET /v1/contexts/:context_id
 
 - `404 Not Found` - Context doesn't exist
 
+### List Child Contexts
+
+```http
+GET /v1/contexts/:context_id/children
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `recursive` | bool | false | Include all descendants, not just direct children |
+| `limit` | int | 256 | Max child contexts to return |
+| `include_provenance` | bool | true | Include provenance in each child |
+| `include_lineage` | bool | true | Include lineage in each child |
+
 ### Create Context
 
 ```http
 POST /v1/contexts/create
 ```
 
+Alias:
+
+```http
+POST /v1/contexts
+```
+
 **Request Body:**
 
 ```json
@@ -235,6 +265,12 @@ Use `next_before_turn_id` from the previous response to continue paging.
 POST /v1/contexts/:context_id/append
 ```
 
+Alias:
+
+```http
+POST /v1/contexts/:context_id/turns
+```
+
 **Request Body:**
 
 ```json
@@ -254,10 +290,13 @@ POST /v1/contexts/:context_id/append
 |-------|------|----------|-------------|
 | `type_id` | string | Yes | Type identifier |
 | `type_version` | int | Yes | Type version |
-| `data` | object | Yes | Turn payload (will be encoded as msgpack) |
+| `data` | object | Yes* | Turn payload (will be encoded as msgpack) |
+| `payload` | object | Yes* | Alias for `data` (for compatibility) |
 | `parent_turn_id` | string | No | Parent turn (default: current head) |
 | `idempotency_key` | string | No | For safe retries |
 
+\*At least one of `data` or `payload` is required.
+
 **Response:**
 
 ```json
@@ -275,7 +314,7 @@ POST /v1/contexts/:context_id/append
 - `409 Conflict` - Invalid parent_turn_id
 - `422 Unprocessable Entity` - Invalid data or missing type
 
-**Note:** The HTTP API accepts JSON `data` and converts it to msgpack internally. Numeric field tags are derived from the type registry. For maximum control over msgpack encoding, use the binary protocol.
+**Note:** The HTTP API accepts JSON payloads and converts them to msgpack internally. If a type descriptor exists, numeric tags are derived from the registry. If no descriptor exists, the JSON structure is still persisted as msgpack (string/numeric keys preserved). For maximum control over encoding, use the binary protocol.
 
 ## Registry
 

frontend/app/page.tsx

@@ -114,6 +114,53 @@ export default function Home() {
       );
     }
 
+    // Link child context to parent context lineage
+    if (event.type === 'context_linked') {
+      setContexts(prev =>
+        prev.map(c => {
+          if (c.context_id === event.data.child_context_id) {
+            return {
+              ...c,
+              lineage: {
+                parent_context_id: event.data.parent_context_id,
+                root_context_id: event.data.root_context_id,
+                spawn_reason: event.data.spawn_reason,
+                child_context_count: c.lineage?.child_context_count ?? 0,
+                child_context_ids: c.lineage?.child_context_ids ?? [],
+              },
+              provenance: {
+                ...(c.provenance ?? {}),
+                parent_context_id: Number(event.data.parent_context_id),
+                root_context_id: event.data.root_context_id
+                  ? Number(event.data.root_context_id)
+                  : c.provenance?.root_context_id,
+                spawn_reason: event.data.spawn_reason ?? c.provenance?.spawn_reason,
+              },
+            };
+          }
+
+          if (c.context_id === event.data.parent_context_id) {
+            const existingChildren = c.lineage?.child_context_ids ?? [];
+            const childContextIds = existingChildren.includes(event.data.child_context_id)
+              ? existingChildren
+              : [...existingChildren, event.data.child_context_id];
+            return {
+              ...c,
+              lineage: {
+                parent_context_id: c.lineage?.parent_context_id,
+                root_context_id: c.lineage?.root_context_id,
+                spawn_reason: c.lineage?.spawn_reason,
+                child_context_count: childContextIds.length,
+                child_context_ids: childContextIds,
+              },
+            };
+          }
+
+          return c;
+        })
+      );
+    }
+
     // Update context activity timestamp on turn append
     if (event.type === 'turn_appended') {
       setContexts(prev =>

frontend/components/live/ActivityFeed.tsx

@@ -156,6 +156,13 @@ function getEventDisplay(event: StoreEvent): {
         icon: <AlertCircle size={12} />,
         label: `${event.data.kind} ${event.data.status_code}: ${event.data.message}`,
       };
+
+    case 'context_linked':
+      return {
+        icon: <Folder size={12} />,
+        label: `Linked to parent ${event.data.parent_context_id}`,
+        contextId: event.data.child_context_id,
+      };
   }
 }
 

frontend/hooks/useEventStream.ts

@@ -7,6 +7,7 @@ import type {
   ConnectionState,
   ContextCreatedEvent,
   ContextMetadataUpdatedEvent,
+  ContextLinkedEvent,
   TurnAppendedEvent,
   ClientConnectedEvent,
   ClientDisconnectedEvent,
@@ -74,6 +75,14 @@ export function useEventStream(options: UseEventStreamOptions = {}): UseEventStr
         if (event.type === 'context_metadata_updated' && event.data.context_id !== contextId) {
           return;
         }
+        if (event.type === 'context_linked') {
+          if (
+            event.data.child_context_id !== contextId &&
+            event.data.parent_context_id !== contextId
+          ) {
+            return;
+          }
+        }
       }
 
       setLastEvent(event);
@@ -154,6 +163,15 @@ export function useEventStream(options: UseEventStreamOptions = {}): UseEventStr
           }
         });
 
+        eventSource.addEventListener('context_linked', (e: MessageEvent) => {
+          try {
+            const data: ContextLinkedEvent = JSON.parse(e.data);
+            handleEvent({ type: 'context_linked', data });
+          } catch (err) {
+            console.error('Failed to parse context_linked event:', err);
+          }
+        });
+
         eventSource.addEventListener('turn_appended', (e: MessageEvent) => {
           try {
             const data: TurnAppendedEvent = JSON.parse(e.data);

frontend/lib/api.ts

@@ -111,6 +111,8 @@ export interface FetchContextsOptions {
   tag?: string;
   /** Include full provenance data for each context. */
   include_provenance?: boolean;
+  /** Include parent/root/children lineage summary for each context. */
+  include_lineage?: boolean;
 }
 
 /**
@@ -131,6 +133,9 @@ export async function fetchContexts(limitOrOptions: number | FetchContextsOption
   if (options.include_provenance) {
     params.set('include_provenance', '1');
   }
+  if (options.include_lineage) {
+    params.set('include_lineage', '1');
+  }
 
   const queryString = params.toString();
   const url = `${API_BASE}/contexts${queryString ? `?${queryString}` : ''}`;
@@ -153,6 +158,103 @@ export async function fetchContexts(limitOrOptions: number | FetchContextsOption
   return response.json();
 }
 
+export interface FetchContextOptions {
+  include_provenance?: boolean;
+  include_lineage?: boolean;
+}
+
+/**
+ * Fetch details for a specific context.
+ */
+export async function fetchContext(
+  contextId: string,
+  options: FetchContextOptions = {}
+): Promise<ContextEntry> {
+  const params = new URLSearchParams();
+  if (options.include_provenance !== false) {
+    params.set('include_provenance', '1');
+  }
+  if (options.include_lineage !== false) {
+    params.set('include_lineage', '1');
+  }
+
+  const queryString = params.toString();
+  const url = `${API_BASE}/contexts/${encodeURIComponent(contextId)}${queryString ? `?${queryString}` : ''}`;
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    let errorData: ErrorResponse | undefined;
+    try {
+      errorData = await response.json();
+    } catch {
+      // Ignore JSON parse errors
+    }
+    throw new ApiError(
+      errorData?.error?.message || `HTTP ${response.status}`,
+      errorData?.error?.code || response.status,
+      errorData
+    );
+  }
+
+  return response.json();
+}
+
+export interface FetchContextChildrenOptions {
+  recursive?: boolean;
+  limit?: number;
+  include_provenance?: boolean;
+  include_lineage?: boolean;
+}
+
+export interface ContextChildrenResponse {
+  context_id: string;
+  recursive: boolean;
+  count: number;
+  children: ContextEntry[];
+}
+
+/**
+ * Fetch child contexts for a parent context.
+ */
+export async function fetchContextChildren(
+  contextId: string,
+  options: FetchContextChildrenOptions = {}
+): Promise<ContextChildrenResponse> {
+  const params = new URLSearchParams();
+  if (options.recursive) {
+    params.set('recursive', '1');
+  }
+  if (options.limit !== undefined) {
+    params.set('limit', String(options.limit));
+  }
+  if (options.include_provenance !== false) {
+    params.set('include_provenance', '1');
+  }
+  if (options.include_lineage !== false) {
+    params.set('include_lineage', '1');
+  }
+
+  const queryString = params.toString();
+  const url = `${API_BASE}/contexts/${encodeURIComponent(contextId)}/children${queryString ? `?${queryString}` : ''}`;
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    let errorData: ErrorResponse | undefined;
+    try {
+      errorData = await response.json();
+    } catch {
+      // Ignore JSON parse errors
+    }
+    throw new ApiError(
+      errorData?.error?.message || `HTTP ${response.status}`,
+      errorData?.error?.code || response.status,
+      errorData
+    );
+  }
+
+  return response.json();
+}
+
 /**
  * Search response from CQL query.
  */

frontend/types/index.ts

@@ -101,6 +101,14 @@ export interface ContextEntry {
   labels?: string[];
   // Provenance (origin story)
   provenance?: import('./provenance').Provenance;
+  // Server-provided lineage summary (optional, include_lineage=1)
+  lineage?: {
+    parent_context_id?: string;
+    root_context_id?: string;
+    spawn_reason?: string;
+    child_context_count: number;
+    child_context_ids: string[];
+  };
 }
 
 // ============================================
@@ -141,6 +149,13 @@ export interface ContextMetadataUpdatedEvent {
   has_provenance: boolean;
 }
 
+export interface ContextLinkedEvent {
+  child_context_id: string;
+  parent_context_id: string;
+  root_context_id?: string;
+  spawn_reason?: string;
+}
+
 export interface ClientConnectedEvent {
   session_id: string;
   client_tag: string;
@@ -164,6 +179,7 @@ export interface ErrorOccurredEvent {
 export type StoreEvent =
   | { type: 'context_created'; data: ContextCreatedEvent }
   | { type: 'context_metadata_updated'; data: ContextMetadataUpdatedEvent }
+  | { type: 'context_linked'; data: ContextLinkedEvent }
   | { type: 'turn_appended'; data: TurnAppendedEvent }
   | { type: 'client_connected'; data: ClientConnectedEvent }
   | { type: 'client_disconnected'; data: ClientDisconnectedEvent }