@decispher/mcp-server 0.1.0

package/src/__tests__/tools.test.ts

@@ -0,0 +1,225 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { promises as fs } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerTools, TOOL_DEFINITIONS } from '../tools.js';
+import type { DecispherClient } from '../decispher-client.js';
+
+type RegisteredTool = { description: string; handler: (args: Record<string, unknown>) => Promise<{ content: Array<{ text: string }> }> };
+type ServerInternals = { _registeredTools: Record<string, RegisteredTool> };
+
+function makeClient(overrides: Partial<DecispherClient> = {}): DecispherClient {
+    return {
+        searchDecisions: vi.fn().mockResolvedValue([
+            { id: 'd-1', title: 'Use Drizzle ORM', type: 'decision', decision: 'Use Drizzle', rationale: null, similarity: 0.92 },
+        ]),
+        getConstraints: vi.fn().mockResolvedValue([
+            { id: 'c-1', title: 'No raw SQL in business logic', decision: 'Always use the repository pattern', rationale: null, severity: 'HIGH' },
+        ]),
+        getConventions: vi.fn().mockResolvedValue([
+            { id: 'v-1', title: 'Pino for logging', decision: 'Use pino structured logging', rationale: null },
+        ]),
+        ask: vi.fn().mockResolvedValue({
+            answer: 'We use Drizzle ORM for type safety.',
+            sources: [{ id: 's-1', title: 'ORM Decision', similarity: 0.88 }],
+            hadContext: true,
+        }),
+        getContextForFile: vi.fn().mockResolvedValue([
+            { id: 'd-2', title: 'Auth middleware', type: 'convention', decision: 'Use jwt-auth', rationale: null, similarity: 0.75 },
+        ]),
+        checkIntent: vi.fn().mockResolvedValue({
+            verdict: 'CLEAR', conflicts: [], relevant: [], latencyMs: 0, creditsConsumed: 0,
+        }),
+        getDecision: vi.fn().mockResolvedValue({
+            id: 'd-1', type: 'decision', title: 'Use Drizzle ORM', problem: null,
+            decision: 'We chose Drizzle over Prisma for type safety.',
+            rationale: 'Drizzle generates typed SQL at compile time.',
+            severity: 'HIGH', status: 'active',
+            alternatives: [{ option: 'Prisma', reasonRejected: 'Runtime schema overhead' }],
+            affectedFiles: ['src/db/index.ts'], tags: ['orm', 'database'],
+            sourceType: null, supersedes: null, supersededBy: null,
+            createdAt: '2024-01-01T00:00:00Z', updatedAt: '2024-01-01T00:00:00Z', lastReviewedAt: null,
+        }),
+        captureDecision: vi.fn().mockResolvedValue({
+            id: 'cap-1', alreadyExists: false, similarityToExisting: null,
+            fusionPending: false, status: 'active', latencyMs: 12,
+        }),
+        ...overrides,
+    } as unknown as DecispherClient;
+}
+
+function getTools(server: McpServer): Record<string, RegisteredTool> {
+    return (server as unknown as ServerInternals)._registeredTools;
+}
+
+describe('MCP tools registration', () => {
+    let server: McpServer;
+    let client: DecispherClient;
+
+    beforeEach(() => {
+        server = new McpServer({ name: 'test', version: '0.0.0' });
+        client = makeClient();
+        registerTools(server, client);
+    });
+
+    it('registers exactly 8 tools', () => {
+        const names = Object.keys(getTools(server)).sort();
+        expect(names).toEqual([
+            'ask_knowledge_base',
+            'capture_decision',
+            'check_conventions',
+            'check_intent',
+            'get_constraints',
+            'get_context_for_file',
+            'get_decision',
+            'search_decisions',
+        ]);
+    });
+
+    it('search_decisions calls client.searchDecisions with query and options', async () => {
+        await getTools(server)['search_decisions']!.handler({ query: 'which ORM do we use?' });
+        expect(client.searchDecisions).toHaveBeenCalledWith('which ORM do we use?', { limit: undefined, types: undefined });
+    });
+
+    it('search_decisions passes limit and types to client', async () => {
+        await getTools(server)['search_decisions']!.handler({ query: 'auth', limit: 3, types: ['constraint'] });
+        expect(client.searchDecisions).toHaveBeenCalledWith('auth', { limit: 3, types: ['constraint'] });
+    });
+
+    it('ask_knowledge_base formats answer with sources', async () => {
+        const result = await getTools(server)['ask_knowledge_base']!.handler({ question: 'which ORM?' });
+        expect(result.content[0]!.text).toContain('We use Drizzle ORM');
+        expect(result.content[0]!.text).toContain('ORM Decision');
+    });
+
+    it('get_constraints calls client.getConstraints', async () => {
+        await getTools(server)['get_constraints']!.handler({});
+        expect(client.getConstraints).toHaveBeenCalled();
+    });
+
+    it('check_conventions calls client.getConventions', async () => {
+        await getTools(server)['check_conventions']!.handler({});
+        expect(client.getConventions).toHaveBeenCalled();
+    });
+
+    it('get_decision formats the full decision body', async () => {
+        const result = await getTools(server)['get_decision']!.handler({ decisionId: 'd-1' });
+        expect(client.getDecision).toHaveBeenCalledWith('d-1');
+        expect(result.content[0]!.text).toContain('Use Drizzle ORM');
+        expect(result.content[0]!.text).toContain('Prisma');
+    });
+
+    it('get_context_for_file reads the file and forwards content + language to client', async () => {
+        const dir = join(tmpdir(), `decispher-tool-${randomUUID()}`);
+        await fs.mkdir(dir, { recursive: true });
+        const path = join(dir, 'auth.ts');
+        try {
+            await fs.writeFile(path, 'export const handler = () => {};');
+
+            await getTools(server)['get_context_for_file']!.handler({ filePath: path });
+
+            expect(client.getContextForFile).toHaveBeenCalledWith(path, {
+                fileContent: 'export const handler = () => {};',
+                language: 'typescript',
+            });
+        } finally {
+            await fs.rm(dir, { recursive: true, force: true });
+        }
+    });
+
+    it('get_context_for_file falls back to path-only when the file cannot be read', async () => {
+        const missing = join(tmpdir(), `decispher-missing-${randomUUID()}.ts`);
+        await getTools(server)['get_context_for_file']!.handler({ filePath: missing });
+        expect(client.getContextForFile).toHaveBeenCalledWith(missing, undefined);
+    });
+
+    it('capture_decision forwards the input and reports a captured id', async () => {
+        const result = await getTools(server)['capture_decision']!.handler({
+            type: 'convention',
+            title: 'Pino for logging',
+            decision: 'Use pino structured logging.',
+            rationale: 'Structured JSON gives us queryable logs.',
+        });
+        expect(client.captureDecision).toHaveBeenCalledWith(expect.objectContaining({
+            type: 'convention',
+            title: 'Pino for logging',
+        }));
+        expect(result.content[0]!.text).toContain('captured: cap-1');
+    });
+
+    it('capture_decision reports already-existing units distinctly', async () => {
+        client = makeClient({
+            captureDecision: vi.fn().mockResolvedValue({
+                id: 'cap-existing', alreadyExists: true, similarityToExisting: 0.973,
+                fusionPending: false, status: 'active', latencyMs: 7,
+            }),
+        });
+        const localServer = new McpServer({ name: 'test', version: '0.0.0' });
+        registerTools(localServer, client);
+
+        const result = await getTools(localServer)['capture_decision']!.handler({
+            type: 'decision',
+            title: 'duplicate',
+            decision: 'body',
+            rationale: 'why',
+        });
+        expect(result.content[0]!.text).toContain('already-known unit: cap-existing');
+        expect(result.content[0]!.text).toContain('0.973');
+    });
+});
+
+describe('WS-E — capabilities-driven registration', () => {
+    let client: DecispherClient;
+
+    beforeEach(() => {
+        client = makeClient();
+    });
+
+    it('only registers tools the server advertised in enabledTools', () => {
+        const server = new McpServer({ name: 'test', version: '0.0.0' });
+        registerTools(server, client, {
+            enabledTools: new Set(['search_decisions', 'check_intent']),
+        });
+        expect(Object.keys(getTools(server)).sort()).toEqual(['check_intent', 'search_decisions']);
+    });
+
+    it('uses server-provided descriptions when supplied', () => {
+        const server = new McpServer({ name: 'test', version: '0.0.0' });
+        registerTools(server, client, {
+            descriptions: { search_decisions: 'OVERRIDDEN by server /capabilities' },
+        });
+        expect(getTools(server)['search_decisions']!.description).toBe('OVERRIDDEN by server /capabilities');
+    });
+
+    it('falls back to embedded description when server omits it', () => {
+        const server = new McpServer({ name: 'test', version: '0.0.0' });
+        registerTools(server, client, { descriptions: {} });
+        const embedded = TOOL_DEFINITIONS.find((d) => d.name === 'get_constraints')!.defaultDescription;
+        expect(getTools(server)['get_constraints']!.description).toBe(embedded);
+    });
+
+    it('TOOL_DEFINITIONS includes capture_decision', () => {
+        const def = TOOL_DEFINITIONS.find((d) => d.name === 'capture_decision');
+        expect(def).toBeDefined();
+        expect(def!.defaultDescription).toContain('Write a new context unit');
+        expect(def!.defaultDescription).toContain('decision');
+        expect(def!.defaultDescription).toContain('convention');
+        expect(def!.defaultDescription).toContain('constraint');
+    });
+
+    it('TOOL_DEFINITIONS covers every wire tool name', () => {
+        const definedNames = TOOL_DEFINITIONS.map((d) => d.name).sort();
+        expect(definedNames).toEqual([
+            'ask_knowledge_base',
+            'capture_decision',
+            'check_conventions',
+            'check_intent',
+            'get_constraints',
+            'get_context_for_file',
+            'get_decision',
+            'search_decisions',
+        ]);
+    });
+});

package/src/decispher-client.ts

@@ -0,0 +1,466 @@
+import { randomUUID } from 'node:crypto';
+
+export type FreshnessTier = 'fresh' | 'aging' | 'stale' | 'fossil';
+
+export interface ConstraintSummary {
+    id: string;
+    title: string;
+    decision: string;
+    rationale: string | null;
+    severity: string;
+}
+
+export interface ConventionSummary {
+    id: string;
+    title: string;
+    decision: string;
+    rationale: string | null;
+}
+
+export interface AskResponse {
+    answer: string;
+    sources: Array<{
+        id: string;
+        title: string;
+        similarity: number;
+        lastReviewedAt?: string | null;
+        ageInDays?: number;
+        freshnessTier?: FreshnessTier;
+    }>;
+    hadContext: boolean;
+    contextUnits?: Array<{
+        id: string;
+        title: string;
+        type: string;
+        lastReviewedAt?: string | null;
+        ageInDays?: number;
+        freshnessTier?: FreshnessTier;
+    }>;
+}
+
+export interface ContextMatch {
+    id: string;
+    title: string;
+    type: string;
+    decision: string;
+    rationale: string | null;
+    similarity: number;
+}
+
+export type IntentVerdict = 'BLOCKED' | 'WARN' | 'CLEAR';
+
+export interface ConflictSummary {
+    severity: string;
+    decisionId: string;
+    title: string;
+    explanation: string;
+}
+
+export interface RelevantSummary {
+    decisionId: string;
+    title: string;
+    type: string;
+    linkScore: number;
+}
+
+export interface IntentCheckResult {
+    verdict: IntentVerdict;
+    conflicts: ConflictSummary[];
+    relevant: RelevantSummary[];
+    latencyMs: number;
+    creditsConsumed: number;
+}
+
+interface EnvelopeBudget {
+    requestedMaxTokens: number | null;
+    estimatedResponseTokens: number;
+    truncated: boolean;
+}
+
+interface EnvelopeMeta {
+    tool: string;
+    latencyMs: number;
+    apiVersion: 'v1';
+}
+
+interface EnvelopeShape<T> {
+    data?: T;
+    citations?: unknown[];
+    budget?: EnvelopeBudget;
+    meta?: EnvelopeMeta;
+}
+
+export interface EnvelopeNotices {
+    truncated: boolean;
+    citationCount: number;
+}
+
+export interface DecisionDetail {
+    id: string;
+    type: string;
+    title: string;
+    problem: string | null;
+    decision: string;
+    rationale: string;
+    severity: string;
+    status: string;
+    alternatives: Array<{ option: string; reasonRejected: string }> | null;
+    affectedFiles: string[];
+    tags: string[];
+    sourceType: string | null;
+    supersedes: string | null;
+    supersededBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+    lastReviewedAt: string | null;
+}
+
+export type CaptureContextUnitType =
+    | 'decision' | 'convention' | 'constraint' | 'rationale'
+    | 'ownership' | 'history' | 'plan';
+
+export interface CaptureDecisionInput {
+    type: CaptureContextUnitType;
+    title: string;
+    decision: string;
+    rationale: string;
+    problem?: string;
+    severity?: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
+    affectedFiles?: string[];
+    tags?: string[];
+    alternatives?: Array<{ option: string; reasonRejected: string }>;
+    /** Agent-reported tokens spent discovering this knowledge. Capped server-side at 100k. */
+    discoveryCostTokens?: number;
+}
+
+export interface CaptureDecisionResult {
+    id: string;
+    alreadyExists: boolean;
+    similarityToExisting: number | null;
+    fusionPending: boolean;
+    status: 'active';
+    latencyMs: number;
+}
+
+// Sprint 4 / ADR-041 — Topic surface ────────────────────────────────────────
+
+export interface TopicSummary {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string | null;
+    readonly unitCount: number;
+}
+
+export interface TopicSpineUnit {
+    readonly id: string;
+    readonly type: string;
+    readonly title: string;
+    readonly severity: string;
+    readonly decision: string;
+    readonly rationale: string | null;
+}
+
+export interface TopicExpansionUnit {
+    readonly id: string;
+    readonly type: string;
+    readonly title: string;
+    readonly severity: string;
+    readonly decision?: string;
+    readonly rationale?: string | null;
+}
+
+export interface TopicContextResult {
+    readonly topicId: string;
+    readonly label: string;
+    readonly description: string | null;
+    readonly spine: readonly TopicSpineUnit[];
+    readonly expansion: readonly TopicExpansionUnit[];
+    readonly projectId: string | null;
+    readonly includeBodies: boolean;
+    readonly spineRequest: boolean;
+}
+
+export interface CapabilityTool {
+    name: string;
+    description: string;
+    costCredits?: number;
+    scopes?: string[];
+    defaultMaxTokens?: number;
+    projectScopedAware?: boolean;
+    status?: string;
+}
+
+export interface CapabilitiesResponse {
+    tools: CapabilityTool[];
+    apiKey: {
+        hasProjectScope: boolean;
+        projectId: string | null;
+        allowedScopes: string[];
+    };
+    apiVersion: string;
+}
+
+export interface HealthResponse {
+    status: string;
+    apiVersion: string;
+    commit: string;
+}
+
+export class DecispherClient {
+    private readonly baseUrl: string;
+    private readonly apiKey: string;
+    private readonly companyId: string;
+    private readonly sessionId: string;
+    /** Notices from the most recent envelope, surfaced by tools.ts in `_meta`. */
+    public lastNotices: EnvelopeNotices | null = null;
+
+    constructor() {
+        this.baseUrl = process.env['DECISPHER_API_URL'] ?? 'http://localhost:3000';
+        this.apiKey = process.env['DECISPHER_API_KEY'] ?? '';
+        this.companyId = process.env['DECISPHER_COMPANY_ID'] ?? '';
+        this.sessionId = process.env['DECISPHER_SESSION_ID'] ?? randomUUID();
+
+        if (!this.apiKey || !this.companyId) {
+            throw new Error('DECISPHER_API_KEY and DECISPHER_COMPANY_ID environment variables are required');
+        }
+    }
+
+    async searchDecisions(query: string, options?: { limit?: number; types?: string[] }): Promise<ContextMatch[]> {
+        const response = await this.post(`/api/companies/${this.companyId}/mcp/search-decisions`, {
+            query,
+            ...(options?.limit !== undefined ? { limit: options.limit } : {}),
+            ...(options?.types ? { types: options.types } : {}),
+        });
+        const data = await this.unwrap<{ results?: ContextMatch[] }>(response);
+        return data?.results ?? [];
+    }
+
+    async getConstraints(options?: { maxTokens?: number; cursor?: string; expand?: string[] }): Promise<ConstraintSummary[]> {
+        const response = await this.post(`/api/companies/${this.companyId}/mcp/get-constraints`, {
+            ...(options?.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {}),
+            ...(options?.cursor !== undefined ? { cursor: options.cursor } : {}),
+            ...(options?.expand ? { expand: options.expand } : {}),
+        });
+        const data = await this.unwrap<{ constraints?: ConstraintSummary[] }>(response);
+        return data?.constraints ?? [];
+    }
+
+    async getConventions(options?: { maxTokens?: number; cursor?: string; expand?: string[] }): Promise<ConventionSummary[]> {
+        const response = await this.post(`/api/companies/${this.companyId}/mcp/check-conventions`, {
+            ...(options?.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {}),
+            ...(options?.cursor !== undefined ? { cursor: options.cursor } : {}),
+            ...(options?.expand ? { expand: options.expand } : {}),
+        });
+        const data = await this.unwrap<{ conventions?: ConventionSummary[] }>(response);
+        return data?.conventions ?? [];
+    }
+
+    async ask(query: string): Promise<AskResponse> {
+        const response = await this.post(`/api/companies/${this.companyId}/mcp/ask-knowledge-base`, { query });
+        const data = await this.unwrap<AskResponse>(response);
+        if (!data) {
+            const status = response.ok ? 'empty response' : `HTTP ${response.status}`;
+            throw new Error(`ask_knowledge_base: Decispher API unreachable or returned an error (${status}). Cannot answer from knowledge base.`);
+        }
+        return data;
+    }
+
+    async getDecision(decisionId: string): Promise<DecisionDetail> {
+        const response = await this.post(`/api/companies/${this.companyId}/mcp/get-decision`, { decisionId });
+        const data = await this.unwrap<DecisionDetail>(response);
+        if (!data) {
+            const status = response.ok ? 'empty response' : `HTTP ${response.status}`;
+            throw new Error(`get_decision: Decispher API returned an error (${status}) for decision ${decisionId}.`);
+        }
+        return data;
+    }
+
+    async checkIntent(description: string, files?: string[]): Promise<IntentCheckResult> {
+        const response = await this.post(
+            `/api/companies/${this.companyId}/mcp/check-intent`,
+            { description, files },
+        );
+        const data = await this.unwrap<IntentCheckResult>(response);
+        if (!data) {
+            const status = response.ok ? 'empty response' : `HTTP ${response.status}`;
+            throw new Error(`check_intent: Decispher API unreachable or returned an error (${status}). Cannot verify intent — do not proceed without manual review.`);
+        }
+        return data;
+    }
+
+    async getContextForFiles(
+        files: Array<{ filePath: string; fileContent?: string; language?: string }>,
+        options?: { limit?: number },
+    ): Promise<ContextMatch[]> {
+        const response = await this.post(
+            `/api/companies/${this.companyId}/mcp/get-context-for-file`,
+            {
+                files: files.map((f) => ({
+                    filePath: f.filePath,
+                    ...(f.fileContent !== undefined ? { fileContent: f.fileContent } : {}),
+                    ...(f.language !== undefined ? { language: f.language } : {}),
+                })),
+                ...(options?.limit !== undefined ? { limit: options.limit } : {}),
+            },
+        );
+        const data = await this.unwrap<{ matches?: ContextMatch[] }>(response);
+        return data?.matches ?? [];
+    }
+
+    async getContextForFile(
+        filePath: string,
+        options?: { fileContent?: string; language?: string; limit?: number },
+    ): Promise<ContextMatch[]> {
+        const response = await this.post(
+            `/api/companies/${this.companyId}/mcp/get-context-for-file`,
+            {
+                filePath,
+                ...(options?.fileContent !== undefined ? { fileContent: options.fileContent } : {}),
+                ...(options?.language !== undefined ? { language: options.language } : {}),
+                ...(options?.limit !== undefined ? { limit: options.limit } : {}),
+            },
+        );
+        const data = await this.unwrap<{ matches?: ContextMatch[] }>(response);
+        return data?.matches ?? [];
+    }
+
+    async listTopics(): Promise<TopicSummary[]> {
+        const response = await this.post(`/api/companies/${this.companyId}/mcp/list-topics`, {});
+        const data = await this.unwrap<{ topics?: TopicSummary[] }>(response);
+        return data?.topics ?? [];
+    }
+
+    async getContextForTopic(
+        topic: string,
+        options?: { includeBodies?: boolean; maxTokens?: number },
+    ): Promise<TopicContextResult> {
+        const response = await this.post(
+            `/api/companies/${this.companyId}/mcp/get-context-for-topic`,
+            {
+                topic,
+                ...(options?.includeBodies !== undefined ? { includeBodies: options.includeBodies } : {}),
+                ...(options?.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {}),
+            },
+        );
+        if (response.status === 404) {
+            throw new Error(`get_context_for_topic: topic "${topic}" not found in this project's scope. Call list_topics for the available set.`);
+        }
+        const data = await this.unwrap<TopicContextResult>(response);
+        if (!data) {
+            const status = response.ok ? 'empty response' : `HTTP ${response.status}`;
+            throw new Error(`get_context_for_topic: Decispher API returned an error (${status}).`);
+        }
+        return data;
+    }
+
+    async captureDecision(input: CaptureDecisionInput): Promise<CaptureDecisionResult> {
+        const response = await this.post(
+            `/api/companies/${this.companyId}/mcp/capture-decision`,
+            input,
+        );
+        if (response.status === 403) {
+            throw new Error('capture_decision: agent capture is disabled by the company administrator.');
+        }
+        if (response.status === 429) {
+            const retryAfterMs = Number(response.headers.get('retry-after-ms') ?? '0');
+            throw new Error(
+                `capture_decision: rate limit exceeded — retry in ~${Math.ceil(retryAfterMs / 1000)}s.`,
+            );
+        }
+        const data = await this.unwrap<CaptureDecisionResult>(response);
+        if (!data) {
+            const status = response.ok ? 'empty response' : `HTTP ${response.status}`;
+            throw new Error(`capture_decision: Decispher API returned an error (${status}).`);
+        }
+        return data;
+    }
+
+    /**
+     * Probe `/api/mcp/health` before the first tool call — no auth required.
+     * Returns null on any network/parse failure so the caller can fall through
+     * to the static tool list instead of crashing the MCP server at startup.
+     */
+    async fetchHealth(): Promise<HealthResponse | null> {
+        try {
+            const response = await fetch(`${this.baseUrl}/api/mcp/health`, { method: 'GET' });
+            if (!response.ok) return null;
+            return (await response.json()) as HealthResponse;
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Pull the tool registry from the server. Returns null if the request fails
+     * or the response shape is unrecognised — caller falls back to the embedded
+     * static tool list so the MCP server still works offline / against an older
+     * API that does not yet expose `/capabilities`.
+     */
+    async fetchCapabilities(): Promise<CapabilitiesResponse | null> {
+        try {
+            const response = await fetch(
+                `${this.baseUrl}/api/companies/${this.companyId}/mcp/capabilities`,
+                { method: 'GET', headers: this.headers() },
+            );
+            if (!response.ok) return null;
+            const parsed = (await response.json()) as Partial<CapabilitiesResponse> | null;
+            if (!parsed || !Array.isArray(parsed.tools) || !parsed.apiKey || typeof parsed.apiVersion !== 'string') {
+                return null;
+            }
+            return parsed as CapabilitiesResponse;
+        } catch {
+            return null;
+        }
+    }
+
+    /** Parse an MCP envelope; transparently passes through legacy un-wrapped responses. */
+    private async unwrap<T>(response: Response): Promise<T | null> {
+        if (!response.ok) {
+            this.lastNotices = null;
+            return null;
+        }
+        let parsed: unknown;
+        try {
+            parsed = await response.json();
+        } catch {
+            this.lastNotices = null;
+            return null;
+        }
+        if (this.isEnvelope<T>(parsed)) {
+            this.lastNotices = {
+                truncated: parsed.budget?.truncated ?? false,
+                citationCount: parsed.citations?.length ?? 0,
+            };
+            return (parsed.data ?? null) as T | null;
+        }
+        this.lastNotices = null;
+        return parsed as T;
+    }
+
+    private isEnvelope<T>(value: unknown): value is EnvelopeShape<T> {
+        if (typeof value !== 'object' || value === null) return false;
+        const v = value as Record<string, unknown>;
+        return 'data' in v && 'meta' in v && 'budget' in v;
+    }
+
+    private async post(path: string, body: unknown): Promise<Response> {
+        try {
+            return await fetch(`${this.baseUrl}${path}`, {
+                method: 'POST',
+                headers: this.headers(),
+                body: JSON.stringify(body),
+            });
+        } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Decispher API unreachable at ${this.baseUrl} — ${msg}`);
+        }
+    }
+
+    private headers(): Record<string, string> {
+        return {
+            'Content-Type': 'application/json',
+            'x-api-key': this.apiKey,
+            'x-decispher-session-id': this.sessionId,
+        };
+    }
+}