feat(native): familiar contract and analytics reads [parked — SDK artifact reconciliation required]

contract-canary.lock.json

@@ -6,24 +6,24 @@
     "releaseManifest": {
       "file": "release-manifest.json",
       "version": "0.1.0",
-      "sha256": "b8bfb62236fc8add4a9baad9f00e5401db15074a2d21fe2847a9158104cefb3c"
+      "sha256": "b248f2d945f77e22d0dee1644e9131aa7d2a20db2f30d06206a974d7a4262dec"
     },
     "artifacts": {
       "core": {
         "packageName": "@opencoven/sdk-core",
         "version": "0.1.0",
         "releaseFile": "tarballs/core/opencoven-sdk-core-0.1.0.tgz",
         "vendorFile": "sdk-core-0.1.0.tgz",
-        "size": 33284,
-        "sha256": "9a574e8bd5178ce2aa20db97e8a741c7c9569515546a2d3089406f41a9d040fe"
+        "size": 33332,
+        "sha256": "dc86c6d4c88dc8273272b70d2014d2b62c80ae7368c9cf1e8eb78440f5fcc9c4"
       },
       "cave": {
         "packageName": "@opencoven/cave-client",
         "version": "0.1.0",
         "releaseFile": "tarballs/cave/opencoven-cave-client-0.1.0.tgz",
         "vendorFile": "cave-client-0.1.0.tgz",
-        "size": 81543,
-        "sha256": "c44544adf8e712d6be1e8686788e63aa0133eb318274d1fb1926138a7da148c0"
+        "size": 85426,
+        "sha256": "de16ce13f2e3be0f6555cfc4413ca3c8f8f1a94f980261a6857c025615e7a14a"
       },
       "coven": {
         "packageName": "@opencoven/coven-client",

docs/developer-toolchains.md

@@ -87,7 +87,7 @@
   Cave revisions, rejects dirty SDK or Cave checkouts, and verifies the
   checked-out HEADs before the canary runs. The SDK lock targets canonical
   `main` commit `acc38488f00860d246c3c553375634d64806eabb` and manifest digest
-  `b8bfb62236fc8add4a9baad9f00e5401db15074a2d21fe2847a9158104cefb3c`.
+  `b248f2d945f77e22d0dee1644e9131aa7d2a20db2f30d06206a974d7a4262dec`.
   The lock also pins the Cave
   producer's Client v1 contract fixture and `hpke-bound-v1` vector digests;
   the canary proves packed vector byte identity and the ancestry of the SDK's

docs/phase1-conformance.md

@@ -30,7 +30,7 @@ the final bytes.
 - SDK evidence contract and registry
   `4736bf2e0d5b16272d79ecf7784c75f376b39b94`;
 - manifest digest
-  `b8bfb62236fc8add4a9baad9f00e5401db15074a2d21fe2847a9158104cefb3c`;
+  `b248f2d945f77e22d0dee1644e9131aa7d2a20db2f30d06206a974d7a4262dec`;
 - canonical package order, release/vendor paths, sizes, and SHA-256 digests.
 
 Chat's Phase 1 source lock now agrees with the frozen Cave and Chat source

phase1-conformance.lock.json

@@ -274,22 +274,22 @@
   "release": {
     "sdkManifest": {
       "version": "0.1.0",
-      "sha256": "b8bfb62236fc8add4a9baad9f00e5401db15074a2d21fe2847a9158104cefb3c"
+      "sha256": "b248f2d945f77e22d0dee1644e9131aa7d2a20db2f30d06206a974d7a4262dec"
     },
     "sdkArtifacts": [
       {
         "packageName": "@opencoven/sdk-core",
         "releaseFile": "tarballs/core/opencoven-sdk-core-0.1.0.tgz",
         "vendorFile": "sdk-core-0.1.0.tgz",
-        "size": 33284,
-        "sha256": "9a574e8bd5178ce2aa20db97e8a741c7c9569515546a2d3089406f41a9d040fe"
+        "size": 33332,
+        "sha256": "dc86c6d4c88dc8273272b70d2014d2b62c80ae7368c9cf1e8eb78440f5fcc9c4"
       },
       {
         "packageName": "@opencoven/cave-client",
         "releaseFile": "tarballs/cave/opencoven-cave-client-0.1.0.tgz",
         "vendorFile": "cave-client-0.1.0.tgz",
-        "size": 81543,
-        "sha256": "c44544adf8e712d6be1e8686788e63aa0133eb318274d1fb1926138a7da148c0"
+        "size": 85426,
+        "sha256": "de16ce13f2e3be0f6555cfc4413ca3c8f8f1a94f980261a6857c025615e7a14a"
       },
       {
         "packageName": "@opencoven/coven-client",

src/contract-canary-artifact-root.test.ts

@@ -320,25 +320,25 @@ describe('contract canary temp directory safety', () => {
     expect(lock.sdk.releaseManifest).toEqual({
       file: 'release-manifest.json',
       version: '0.1.0',
-      sha256: 'b8bfb62236fc8add4a9baad9f00e5401db15074a2d21fe2847a9158104cefb3c',
+      sha256: 'b248f2d945f77e22d0dee1644e9131aa7d2a20db2f30d06206a974d7a4262dec',
     });
     expect(Object.keys(lock.sdk.artifacts)).toEqual(['core', 'cave', 'coven', 'sdk']);
     expect(lock.sdk.artifacts.core).toEqual({
       packageName: '@opencoven/sdk-core',
       version: '0.1.0',
       releaseFile: 'tarballs/core/opencoven-sdk-core-0.1.0.tgz',
       vendorFile: 'sdk-core-0.1.0.tgz',
-      size: 33284,
-      sha256: '9a574e8bd5178ce2aa20db97e8a741c7c9569515546a2d3089406f41a9d040fe',
+      size: 33332,
+      sha256: 'dc86c6d4c88dc8273272b70d2014d2b62c80ae7368c9cf1e8eb78440f5fcc9c4',
     });
 
     expect(lock.sdk.artifacts.cave).toEqual({
       packageName: '@opencoven/cave-client',
       version: '0.1.0',
       releaseFile: 'tarballs/cave/opencoven-cave-client-0.1.0.tgz',
       vendorFile: 'cave-client-0.1.0.tgz',
-      size: 81543,
-      sha256: 'c44544adf8e712d6be1e8686788e63aa0133eb318274d1fb1926138a7da148c0',
+      size: 85426,
+      sha256: 'de16ce13f2e3be0f6555cfc4413ca3c8f8f1a94f980261a6857c025615e7a14a',
     });
     expect(lock.cave.repository).toBe('OpenCoven/coven-cave');
     expect(lock.cave.revision).toBe('6325fc4c1154c7d7398074a9760a2e2dc323b424');

src/familiars/cave-source.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { QueryAdapter } from '../lib/sdk/query-adapter';
+import { createCaveFamiliarsSource } from './cave-source';
+import type { Capability, QueryResult } from './source';
+
+function ok<T>(data: T): QueryResult<T> {
+  return { status: 'ok', data };
+}
+
+function makeQueryAdapter(overrides: Partial<QueryAdapter> = {}): QueryAdapter {
+  return {
+    listFamiliars: vi.fn().mockResolvedValue(ok({ data: [] })),
+    listProjects: vi.fn().mockResolvedValue(ok({ data: [] })),
+    listConversations: vi.fn().mockResolvedValue(ok({ data: [] })),
+    getConversation: vi.fn().mockResolvedValue({ status: 'not_ready' }),
+    listMessages: vi.fn().mockResolvedValue(ok({ data: [] })),
+    familiarContract: vi.fn().mockResolvedValue({ status: 'not_ready' }),
+    familiarAnalytics: vi.fn().mockResolvedValue({ status: 'not_ready' }),
+    invalidate: vi.fn(),
+    dispose: vi.fn(),
+    ...overrides,
+  };
+}
+
+const CAPABILITIES: ReadonlySet<Capability> = new Set(['familiars', 'familiar-contract']);
+
+describe('createCaveFamiliarsSource', () => {
+  it('maps a familiars page through mapFamiliarSummary', async () => {
+    const queryAdapter = makeQueryAdapter({
+      listFamiliars: vi
+        .fn()
+        .mockResolvedValue(ok({ data: [{ id: 'astra', displayName: 'Astra', role: 'Guide' }] })),
+    });
+    const source = createCaveFamiliarsSource({ queryAdapter, capabilities: CAPABILITIES });
+
+    const result = await source.familiars();
+    expect(result).toEqual(
+      ok({ data: [{ id: 'astra', name: 'Astra', role: 'Guide', status: 'offline' }] }),
+    );
+  });
+
+  it('passes a non-ok familiars result straight through unmapped', async () => {
+    const queryAdapter = makeQueryAdapter({
+      listFamiliars: vi.fn().mockResolvedValue({ status: 'error', code: 'service_unavailable' }),
+    });
+    const source = createCaveFamiliarsSource({ queryAdapter, capabilities: CAPABILITIES });
+
+    expect(await source.familiars()).toEqual({ status: 'error', code: 'service_unavailable' });
+  });
+
+  it('fetches a familiar contract by id and maps it to a detail', async () => {
+    const familiarContract = vi.fn().mockResolvedValue(
+      ok({
+        id: 'astra',
+        present: { soul: true, identity: true, ward: true, memory: true },
+        report: { specVersion: '0.1.0', pass: true, properties: [], violations: [], warnings: [] },
+      }),
+    );
+    const queryAdapter = makeQueryAdapter({ familiarContract });
+    const source = createCaveFamiliarsSource({ queryAdapter, capabilities: CAPABILITIES });
+
+    const result = await source.familiar('astra');
+    expect(familiarContract).toHaveBeenCalledWith('astra');
+    expect(result.status).toBe('ok');
+    expect(result).toMatchObject({ data: { id: 'astra' } });
+  });
+
+  it('requests the default 7d window when none is given, and maps the response', async () => {
+    const familiarAnalytics = vi.fn().mockResolvedValue(
+      ok({
+        generatedAt: '2026-08-25T00:00:00.000Z',
+        windows: {
+          '7d': {
+            attempts: 1,
+            completed: 1,
+            failed: 0,
+            cancelled: 0,
+            successRate: 1,
+            toolCalls: 4,
+            toolFailures: 0,
+            models: [],
+            harnesses: [],
+            coverage: {},
+          },
+        },
+        recentAttempts: [],
+        backfill: { state: 'complete', imported: 1 },
+      }),
+    );
+    const queryAdapter = makeQueryAdapter({ familiarAnalytics });
+    const source = createCaveFamiliarsSource({ queryAdapter, capabilities: CAPABILITIES });
+
+    const result = await source.activity('astra');
+    expect(familiarAnalytics).toHaveBeenCalledWith('astra', { window: '7d' });
+    expect(result).toMatchObject({ status: 'ok', data: { window: '7d', attempts: 1 } });
+  });
+
+  it('requests an explicit window and returns not_found when Cave omits it from the response', async () => {
+    const familiarAnalytics = vi.fn().mockResolvedValue(
+      ok({
+        generatedAt: '2026-08-25T00:00:00.000Z',
+        windows: {},
+        recentAttempts: [],
+        backfill: { state: 'not-started', imported: 0 },
+      }),
+    );
+    const queryAdapter = makeQueryAdapter({ familiarAnalytics });
+    const source = createCaveFamiliarsSource({ queryAdapter, capabilities: CAPABILITIES });
+
+    const result = await source.activity('astra', '14d');
+    expect(familiarAnalytics).toHaveBeenCalledWith('astra', { window: '14d' });
+    expect(result).toEqual({ status: 'error', code: 'not_found' });
+  });
+
+  it('passes a non-ok analytics result straight through without mapping', async () => {
+    const queryAdapter = makeQueryAdapter({
+      familiarAnalytics: vi.fn().mockResolvedValue({ status: 'reconcile_required' }),
+    });
+    const source = createCaveFamiliarsSource({ queryAdapter, capabilities: CAPABILITIES });
+
+    expect(await source.activity('astra')).toEqual({ status: 'reconcile_required' });
+  });
+
+  it('maps a conversations page and a messages page through their mappers', async () => {
+    const queryAdapter = makeQueryAdapter({
+      listConversations: vi
+        .fn()
+        .mockResolvedValue(
+          ok({ data: [{ id: 'c1', familiarId: 'astra', updatedAt: '2026-08-25T00:00:00.000Z' }] }),
+        ),
+      listMessages: vi.fn().mockResolvedValue(
+        ok({
+          data: [
+            {
+              id: 'm1',
+              conversationId: 'c1',
+              parentId: null,
+              role: 'user',
+              text: 'Hi',
+              createdAt: '2026-08-25T00:00:00.000Z',
+              attachmentCount: 0,
+              toolCount: 0,
+            },
+          ],
+        }),
+      ),
+    });
+    const source = createCaveFamiliarsSource({ queryAdapter, capabilities: CAPABILITIES });
+
+    const conversations = await source.conversations();
+    expect(conversations).toMatchObject({
+      data: { data: [{ id: 'c1', failed: false, pending: false }] },
+    });
+
+    const messages = await source.messages('c1');
+    expect(queryAdapter.listMessages).toHaveBeenCalledWith('c1');
+    expect(messages).toMatchObject({
+      data: { data: [{ id: 'm1', role: 'user', isError: false }] },
+    });
+  });
+
+  it('returns the capabilities it was constructed with, unchanged', () => {
+    const source = createCaveFamiliarsSource({
+      queryAdapter: makeQueryAdapter(),
+      capabilities: CAPABILITIES,
+    });
+    expect(source.capabilities()).toBe(CAPABILITIES);
+  });
+});

src/familiars/cave-source.ts

@@ -0,0 +1,93 @@
+import type { Page } from '@opencoven/sdk-core/browser';
+
+import type { QueryAdapter } from '../lib/sdk/query-adapter';
+import {
+  mapConversationSummary,
+  mapFamiliarActivity,
+  mapFamiliarDetail,
+  mapFamiliarSummary,
+  mapThreadMessage,
+} from './mappers';
+import type {
+  ActivityWindow,
+  Capability,
+  ConversationSummary,
+  FamiliarActivity,
+  FamiliarDetail,
+  FamiliarSummary,
+  FamiliarsSource,
+  QueryResult,
+  ThreadMessage,
+} from './source';
+
+/**
+ * `FamiliarsSource` over `QueryAdapter` and the managed `CaveClient`.
+ *
+ * Every method is a thin fetch-then-map: `QueryAdapter` owns the TTL / LRU /
+ * abort / epoch semantics the rest of the production shell already uses,
+ * and `./mappers.ts` owns the SDK-wire-type -> view-type translation. This
+ * module adds no caching, retry, or formatting logic of its own.
+ */
+
+const DEFAULT_ACTIVITY_WINDOW: ActivityWindow = '7d';
+
+export type CaveFamiliarsSourceOptions = Readonly<{
+  queryAdapter: QueryAdapter;
+  /**
+   * The set of capability names the connected Cave instance advertises
+   * (`CaveHealth.capabilities`). A snapshot rather than a live subscription:
+   * the shell re-creates the source when connection state changes.
+   */
+  capabilities: ReadonlySet<Capability>;
+}>;
+
+function mapResult<T, U>(result: QueryResult<T>, map: (value: T) => U): QueryResult<U> {
+  return result.status === 'ok' ? { status: 'ok', data: map(result.data) } : result;
+}
+
+function mapPageResult<T, U>(
+  result: QueryResult<Page<T>>,
+  map: (value: T) => U,
+): QueryResult<Page<U>> {
+  return result.status === 'ok'
+    ? { status: 'ok', data: { ...result.data, data: result.data.data.map(map) } }
+    : result;
+}
+
+export function createCaveFamiliarsSource(options: CaveFamiliarsSourceOptions): FamiliarsSource {
+  const { queryAdapter, capabilities } = options;
+
+  return Object.freeze({
+    async familiars(): Promise<QueryResult<Page<FamiliarSummary>>> {
+      return mapPageResult(await queryAdapter.listFamiliars(), mapFamiliarSummary);
+    },
+    async familiar(id: string): Promise<QueryResult<FamiliarDetail>> {
+      return mapResult(await queryAdapter.familiarContract(id), mapFamiliarDetail);
+    },
+    async activity(
+      id: string,
+      window: ActivityWindow = DEFAULT_ACTIVITY_WINDOW,
+    ): Promise<QueryResult<FamiliarActivity>> {
+      const result = await queryAdapter.familiarAnalytics(id, { window });
+      if (result.status !== 'ok') {
+        return result;
+      }
+      const activity = mapFamiliarActivity(result.data, window);
+      // Cave omitted the requested window (e.g. an instance with a shorter
+      // retained history than `window` implies) rather than the read
+      // failing outright.
+      return activity === undefined
+        ? { status: 'error', code: 'not_found' }
+        : { status: 'ok', data: activity };
+    },
+    async conversations(): Promise<QueryResult<Page<ConversationSummary>>> {
+      return mapPageResult(await queryAdapter.listConversations(), mapConversationSummary);
+    },
+    async messages(conversationId: string): Promise<QueryResult<Page<ThreadMessage>>> {
+      return mapPageResult(await queryAdapter.listMessages(conversationId), mapThreadMessage);
+    },
+    capabilities(): ReadonlySet<Capability> {
+      return capabilities;
+    },
+  });
+}