@decentrys/dri-sdk 0.1.0

package/src/client.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, it, vi } from 'vitest';
+import { DecentrysDri, DriError, type FetchLike } from './client';
+import { MissingDisclosureError, type RecoveryIndex } from './model';
+
+function ok(body: unknown): ReturnType<FetchLike> {
+  return Promise.resolve({ ok: true, status: 200, text: () => Promise.resolve(JSON.stringify(body)) });
+}
+
+function client(fetchImpl: FetchLike) {
+  return new DecentrysDri({ apiKey: 'dk_live_test', fetch: fetchImpl });
+}
+
+const INDEX: RecoveryIndex = {
+  recoveryCaseId: 'case-1',
+  caseRef: 'REC-2026-0001',
+  incidentRef: 'INC-2026-0007',
+  score: 58,
+  band: 'MODERATE',
+  bandMeaning: 'Value is traceable and attributed, but sits in non-custodial wallets.',
+  factors: [{ factor: 'baseline', contribution: 30, note: 'Neutral starting position.' }],
+  modelVersion: 'recovery-outlook-1.0.0',
+  inputsHash: 'abc123',
+  computedAt: '2026-02-01T00:00:00.000Z',
+  funnel: {
+    totalLossUsd: 1_000_000, byState: {}, locatedUsd: 400_000, atInterventionPointUsd: 250_000,
+    freezeRequestedUsd: 0, frozenUsd: 0, recoveredUsd: 0, obfuscatedUsd: 0, lostUsd: 0,
+    untracedUsd: 0, probabilisticUsd: 0, accountedUsd: 1_000_000, unaccountedUsd: 0, reconciles: true,
+  },
+  analyticalOnly: true,
+  disclaimer: 'The Recovery Outlook is an analytical indicator. It is not a probability and not a forecast.',
+  notes: [],
+};
+
+describe('construction', () => {
+  it('requires a key', () => {
+    expect(() => new DecentrysDri({ apiKey: '' })).toThrow(/apiKey is required/);
+  });
+
+  /**
+   * The single most important line in this file.
+   *
+   * An investigation names third parties who are, so far as the record shows,
+   * uninvolved businesses. A publishable key is readable by anyone who
+   * downloads the artifact carrying it, so accepting one here would mean
+   * anybody who unzipped an app could start opening cases that name people.
+   * The server refuses it too — `dri:investigate` is not a publishable scope —
+   * but a clear failure at construction beats a 403 three weeks in.
+   */
+  it('refuses a publishable key outright', () => {
+    expect(() => new DecentrysDri({ apiKey: 'dk_pub_live_abc' }))
+      .toThrow(/publishable key/);
+    expect(() => new DecentrysDri({ apiKey: 'dk_pub_live_abc' }))
+      .toThrow(/names third parties/);
+  });
+});
+
+/**
+ * The contract, and why it is the opposite of Protect's.
+ *
+ * Protect never throws: a wallet must stay usable when Decentrys is down.
+ * Nothing here is on a signing path. A trace that silently returned an empty
+ * graph when the service was unreachable would tell a responder the value had
+ * vanished at exactly the moment it was still moving — and nothing about that
+ * failure would be visible.
+ */
+describe('failure behaviour', () => {
+  it('throws rather than returning an empty graph when unreachable', async () => {
+    const dri = client(() => Promise.reject(new Error('connection refused')));
+    await expect(dri.getFlowGraph('inv-1')).rejects.toBeInstanceOf(DriError);
+  });
+
+  it('surfaces the API’s own message and code', async () => {
+    const dri = client(() => Promise.resolve({
+      ok: false, status: 403,
+      text: () => Promise.resolve(JSON.stringify({ code: 'FORBIDDEN', message: 'API key scope: dri:investigate' })),
+    }));
+
+    const error = await dri.getFlowGraph('inv-1').catch((e: unknown) => e);
+    expect((error as DriError).message).toBe('API key scope: dri:investigate');
+    expect((error as DriError).code).toBe('FORBIDDEN');
+    expect((error as DriError).status).toBe(403);
+  });
+
+  it('gives up at the deadline instead of hanging a caller’s process', async () => {
+    const hang: FetchLike = (_u, init) => new Promise((_res, rej) => {
+      init.signal?.addEventListener('abort', () => rej(Object.assign(new Error('aborted'), { name: 'AbortError' })));
+    });
+    const dri = new DecentrysDri({ apiKey: 'dk_live_test', timeoutMs: 20, fetch: hang });
+
+    const error = await dri.traceFunds({ investigationId: 'inv-1' }).catch((e: unknown) => e);
+    expect((error as DriError).message).toContain('No response within');
+  });
+});
+
+describe('Recovery Index', () => {
+  /**
+   * The requirement Stage 8 exists to satisfy, enforced at the boundary.
+   *
+   * The server already checks this. Duplicating it here is the point: an
+   * integrator's dashboard renders whatever arrives, and "58 — MODERATE"
+   * beside the word recovery is read as a rate by everyone who sees it. A
+   * proxy stripping fields, an older deployment or a hand-rolled response must
+   * not be able to turn an analytical estimate into a bare number.
+   */
+  it('refuses a score that arrives without its disclaimer', async () => {
+    const dri = client(() => ok({ data: { ...INDEX, disclaimer: '' } }));
+
+    await expect(dri.getRecoveryIndex('case-1')).rejects.toBeInstanceOf(MissingDisclosureError);
+  });
+
+  it('refuses a score that is not marked analytical-only', async () => {
+    const dri = client(() => ok({ data: { ...INDEX, analyticalOnly: false } }));
+
+    await expect(dri.getRecoveryIndex('case-1')).rejects.toBeInstanceOf(MissingDisclosureError);
+  });
+
+  /**
+   * A disclosure failure is not a transport failure. A caller that wraps DRI
+   * calls in a retry-on-DriError loop would otherwise treat a stripped
+   * disclaimer as a blip and retry it forever, never surfacing the one problem
+   * that actually needed a human.
+   */
+  it('does not disguise a missing disclaimer as a network error', async () => {
+    const dri = client(() => ok({ data: { ...INDEX, disclaimer: '   ' } }));
+
+    const error = await dri.getRecoveryIndex('case-1').catch((e: unknown) => e);
+    expect(error).not.toBeInstanceOf(DriError);
+    expect((error as Error).name).toBe('MissingDisclosureError');
+  });
+
+  it('returns the score with its model version and inputs hash, so a figure is reproducible', async () => {
+    const dri = client(() => ok({ data: INDEX }));
+
+    const index = await dri.getRecoveryIndex('case-1');
+    expect(index.score).toBe(58);
+    expect(index.modelVersion).toBe('recovery-outlook-1.0.0');
+    expect(index.inputsHash).toBe('abc123');
+    expect(index.disclaimer).toContain('not a probability');
+  });
+});
+
+describe('request shape', () => {
+  it('keeps the key in a header, never in the URL', async () => {
+    const fetchImpl = vi.fn<FetchLike>().mockImplementation(() => ok({ data: {} }));
+    await client(fetchImpl).getFlowGraph('inv-1');
+
+    const [url, init] = fetchImpl.mock.calls[0]!;
+    expect(url).not.toContain('dk_live_test');
+    expect(init.headers['x-api-key']).toBe('dk_live_test');
+  });
+
+  /**
+   * A case reference or an identifier goes into a path segment. Left unencoded
+   * a stray slash would silently address a different route — on this API,
+   * plausibly a different customer's.
+   */
+  it('encodes identifiers into the path', async () => {
+    const fetchImpl = vi.fn<FetchLike>().mockImplementation(() => ok({ data: INDEX }));
+    await client(fetchImpl).getRecoveryIndex('case/../other');
+
+    expect(fetchImpl.mock.calls[0]![0]).toBe(
+      'https://api.decentrys.com/v1/dri/cases/case%2F..%2Fother/recovery-index',
+    );
+  });
+
+  it('omits fromNodeId entirely when none is given, so the server picks the frontier', async () => {
+    const fetchImpl = vi.fn<FetchLike>().mockImplementation(() => ok({ data: {} }));
+    await client(fetchImpl).traceFunds({ investigationId: 'inv-1' });
+
+    const [url, init] = fetchImpl.mock.calls[0]!;
+    expect(url).toContain('/v1/dri/investigations/inv-1/trace');
+    expect(JSON.parse(init.body!)).toEqual({});
+  });
+
+  it('sends the seed as chain and address on creation', async () => {
+    const fetchImpl = vi.fn<FetchLike>().mockImplementation(() => ok({ data: {} }));
+    await client(fetchImpl).createInvestigation({
+      title: 'Bridge drain', chain: 'ethereum', address: '0xseed', maxHops: 3,
+    });
+
+    const body = JSON.parse(fetchImpl.mock.calls[0]![1].body!) as Record<string, unknown>;
+    expect(body).toEqual({ title: 'Bridge drain', chain: 'ethereum', address: '0xseed', maxHops: 3 });
+  });
+
+  /**
+   * The list endpoints wrap their rows, and a caller wants the rows. Unwrapping
+   * here rather than in every call site is what keeps `listCases()` usable as
+   * the way to find a `recoveryCaseId`.
+   */
+  it('unwraps list responses to the rows themselves', async () => {
+    const dri = client(() => ok({ data: { cases: [{ caseRef: 'REC-2026-0001' }] } }));
+    const cases = await dri.listCases();
+    expect(cases).toHaveLength(1);
+    expect(cases[0]!.caseRef).toBe('REC-2026-0001');
+  });
+});
+
+/**
+ * There is no method here that freezes, seizes, holds, transmits or returns
+ * anything, and there must never be one. Decentrys never takes custody:
+ * recovered value moves between the parties entitled to it and never through
+ * us, so a method that appeared to do otherwise would be a claim the company
+ * cannot make — and an SDK surface is exactly where somebody would add one for
+ * convenience.
+ */
+describe('what this client cannot do', () => {
+  it('exposes no method that acts on assets', () => {
+    const methods = Object.getOwnPropertyNames(DecentrysDri.prototype);
+    for (const name of methods) {
+      expect(name, name).not.toMatch(/freeze|seize|recover(?!yIndex)|refund|return|withdraw|custody|transmit/i);
+    }
+  });
+
+  it('exposes exactly the seven documented capabilities plus the two lookups', () => {
+    const methods = Object.getOwnPropertyNames(DecentrysDri.prototype)
+      .filter((name) => name !== 'constructor' && !name.startsWith('request'));
+
+    expect(new Set(methods)).toEqual(new Set([
+      'createInvestigation', 'traceFunds', 'getFlowGraph', 'identifyInterventionPoints',
+      'getRecoveryIndex', 'generateEvidencePackage', 'getInvestigationTimeline',
+      'listInvestigations', 'listCases',
+    ]));
+  });
+});

package/src/client.ts

@@ -0,0 +1,343 @@
+/**
+ * The DRI client — Digital Recovery Intelligence.
+ *
+ * Fund tracing, attribution, intervention-point identification and evidence
+ * packages, for the organisation whose value was taken.
+ *
+ * **This client throws**, like Sentinel and Risk and unlike Protect. Protect
+ * sits between a user and a signing screen, so a bad minute must never cost
+ * someone their transaction. Nothing here is on a signing path: a trace that
+ * quietly returned an empty graph when the service was unreachable would tell
+ * a responder the value had vanished at exactly the moment it was still
+ * moving, and that failure is invisible by construction. Better a loud error.
+ *
+ * **A publishable key is refused at construction.** An investigation names
+ * third parties who are, so far as the record shows, uninvolved businesses.
+ * That must never run behind a credential shipped inside a client artifact,
+ * where anyone who downloads it can read it and start naming people. The
+ * server refuses one too — `dri:investigate` is not a publishable scope and
+ * `/v1/dri/` is not a publishable path — but a clear error here beats a 403
+ * three weeks into an integration.
+ *
+ * What this client cannot do, at all, and by design:
+ *
+ *  - It cannot freeze, seize, hold, transmit or return anything. Decentrys
+ *    never takes custody of recovered value; it moves between the parties
+ *    entitled to it and never through us.
+ *  - It cannot record that a custodian, an issuer, a court or an agency acted.
+ *    Those states name the party who acted and are written by staff, because
+ *    an audit trail that says Decentrys did something it did not is worse than
+ *    no trail.
+ *  - It cannot give legal advice. Decentrys is not a law firm, a
+ *    law-enforcement agency or a licensed recovery agent.
+ */
+
+import {
+  assertAnalyticalDisclosure,
+  type EvidencePackage, type EvidenceRecipientType, type FlowGraph, type InterventionAnalysis,
+  type InvestigationSummary, type InvestigationTimeline, type RecoveryCaseSummary,
+  type RecoveryIndex, type TraceResult,
+} from './model';
+
+export const SDK_VERSION = '0.1.0';
+
+const DEFAULT_BASE_URL = 'https://api.decentrys.com';
+
+/**
+ * Ten seconds, as elsewhere. A trace expands one address against rate-limited
+ * public endpoints, so it is the slowest call here by some margin — but a
+ * client that waits indefinitely is a client that hangs, and the graph is
+ * persisted server-side either way, so a timed-out trace is re-readable rather
+ * than lost.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export type FetchLike = (
+  url: string,
+  init: { method: string; headers: Record<string, string>; body?: string; signal?: AbortSignal },
+) => Promise<{ ok: boolean; status: number; text: () => Promise<string> }>;
+
+export class DriError extends Error {
+  constructor(readonly status: number, message: string, readonly code?: string) {
+    super(message);
+    this.name = 'DriError';
+  }
+}
+
+export interface DriConfig {
+  apiKey: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  fetch?: FetchLike;
+}
+
+export interface CreateInvestigationInput {
+  /** What this case is, in a form a reader will recognise months later. */
+  title: string;
+  chain: string;
+  /** The seed: the victim contract, or the first attacker wallet. */
+  address: string;
+  /** Links the case to a declared incident of your own organisation. */
+  incidentId?: string;
+  /** 1-4. The graph will not be expanded past this distance from the seed. */
+  maxHops?: number;
+}
+
+export interface TraceFundsInput {
+  investigationId: string;
+  /**
+   * Which address to follow. Omit to take the shallowest one nobody has looked
+   * past yet, which is the ordering that keeps a graph anchored in what was
+   * directly traced.
+   */
+  fromNodeId?: string;
+}
+
+export interface EvidencePackageInput {
+  recoveryCaseId: string;
+  recipientType: EvidenceRecipientType;
+  recipientName: string;
+  /** Narrows the package to one identified destination, when there is one. */
+  recoveryLeadId?: string;
+}
+
+export class DecentrysDri {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly timeoutMs: number;
+  private readonly fetchImpl: FetchLike;
+
+  constructor(config: DriConfig) {
+    if (!config.apiKey?.trim()) {
+      throw new Error('DRI: an apiKey is required. Create one at https://decentrys.com/developers.');
+    }
+    if (config.apiKey.startsWith('dk_pub_')) {
+      throw new Error(
+        'DRI: that is a publishable key. An investigation names third parties, and that must never run behind a '
+        + 'credential shipped inside a client where anyone who downloads it can read it. Use a secret key, '
+        + 'server-side.',
+      );
+    }
+
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.fetchImpl = config.fetch ?? resolveFetch();
+  }
+
+  // --- Investigations ------------------------------------------------------
+
+  /**
+   * Open an investigation seeded on one address.
+   *
+   * Nothing is traced yet. The seed node exists so the graph has a root before
+   * any chain call is made, which means a case can be opened and worked on
+   * even while a provider is unreachable.
+   */
+  createInvestigation(input: CreateInvestigationInput): Promise<FlowGraph> {
+    return this.request<FlowGraph>('POST', '/v1/dri/investigations', {
+      title: input.title,
+      chain: input.chain,
+      address: input.address,
+      ...(input.incidentId ? { incidentId: input.incidentId } : {}),
+      ...(input.maxHops === undefined ? {} : { maxHops: input.maxHops }),
+    });
+  }
+
+  listInvestigations(limit?: number): Promise<InvestigationSummary[]> {
+    const query = limit === undefined ? '' : `?limit=${encodeURIComponent(String(limit))}`;
+    return this.request<{ investigations: InvestigationSummary[] }>(
+      'GET', `/v1/dri/investigations${query}`,
+    ).then((body) => body.investigations);
+  }
+
+  /**
+   * Follow the value one address further.
+   *
+   * One address, one hop, per call — and that is a deliberate limit rather
+   * than an unfinished feature. The public endpoints a trace reads are rate
+   * limited, and an unattended crawl to four hops exhausts them; the result
+   * then reads as "the funds vanished" rather than "we ran out of quota",
+   * which on this product is the worst possible way to be wrong. Call it in a
+   * loop if you want depth, and read `coverage.truncated` on each result.
+   */
+  traceFunds(input: TraceFundsInput): Promise<TraceResult> {
+    return this.request<TraceResult>('POST', `/v1/dri/investigations/${encode(input.investigationId)}/trace`, {
+      ...(input.fromNodeId ? { fromNodeId: input.fromNodeId } : {}),
+    });
+  }
+
+  /** The graph as it stands: every address reached, and how it was reached. */
+  getFlowGraph(investigationId: string): Promise<FlowGraph> {
+    return this.request<FlowGraph>('GET', `/v1/dri/investigations/${encode(investigationId)}`);
+  }
+
+  /**
+   * Where a third party could act, and where attribution stops.
+   *
+   * Read both halves. An intervention point is a party who holds value and can
+   * be contacted, served or subpoenaed — whether it does anything is a matter
+   * for it, its regulators and any legal process, never for Decentrys. An
+   * attribution limit is where the trail stops being provable, and a case that
+   * reaches one has established an answer rather than failed.
+   *
+   * Every point carries `observedPath`. False means the connection to this
+   * case runs through mixing or privacy infrastructure and is therefore
+   * inference — an observation about a counterparty, never an accusation about
+   * a person. `inferredPoints()` isolates them.
+   */
+  identifyInterventionPoints(investigationId: string): Promise<InterventionAnalysis> {
+    return this.request<InterventionAnalysis>(
+      'GET', `/v1/dri/investigations/${encode(investigationId)}/intervention-points`,
+    );
+  }
+
+  /**
+   * What happened on this case, oldest first, with the acting party on every
+   * entry.
+   *
+   * Merges the recovery record in when the incident behind the investigation
+   * has a case. Entries attributed to anyone other than Decentrys are recorded
+   * as reported by that party — Decentrys did not perform them and does not
+   * verify them.
+   */
+  getInvestigationTimeline(investigationId: string, limit?: number): Promise<InvestigationTimeline> {
+    const query = limit === undefined ? '' : `?limit=${encodeURIComponent(String(limit))}`;
+    return this.request<InvestigationTimeline>(
+      'GET', `/v1/dri/investigations/${encode(investigationId)}/timeline${query}`,
+    );
+  }
+
+  // --- Recovery cases ------------------------------------------------------
+
+  /**
+   * The recovery cases of your organisation.
+   *
+   * A case is opened as part of an engagement, against a declared incident and
+   * a stated loss; the tranche ledger behind it is analyst work, so it is not
+   * something an API call brings into existence. This is how you find the
+   * `recoveryCaseId` that `getRecoveryIndex` and `generateEvidencePackage`
+   * take — and `getFlowGraph` reports it too, for an investigation attached to
+   * one.
+   */
+  listCases(limit?: number): Promise<RecoveryCaseSummary[]> {
+    const query = limit === undefined ? '' : `?limit=${encodeURIComponent(String(limit))}`;
+    return this.request<{ cases: RecoveryCaseSummary[] }>('GET', `/v1/dri/cases${query}`)
+      .then((body) => body.cases);
+  }
+
+  /**
+   * The Recovery Index for a case.
+   *
+   * An **analytical estimate** of the current evidentiary and custodial
+   * position, produced by a versioned model from the evidence recorded in the
+   * case. It is not a probability, not a forecast, and not a representation
+   * that any value will be recovered. `modelVersion` and `inputsHash` come
+   * back with it so any figure shown to a client can be reproduced exactly
+   * from the record it was computed from.
+   *
+   * The disclaimer travels in the payload, and this method **refuses a
+   * response that does not carry it** rather than returning a bare number.
+   * That check is deliberately duplicated from the server: an integrator's
+   * dashboard renders whatever arrives, and "58 — MODERATE" beside the word
+   * recovery is read as a rate by everyone who sees it. If the caveat ever
+   * stops arriving, failing here is the only outcome that keeps the score
+   * honest.
+   */
+  getRecoveryIndex(recoveryCaseId: string): Promise<RecoveryIndex> {
+    return this.request<RecoveryIndex>('GET', `/v1/dri/cases/${encode(recoveryCaseId)}/recovery-index`)
+      .then(assertAnalyticalDisclosure);
+  }
+
+  /**
+   * Prepare an evidence package for a recipient.
+   *
+   * **Prepared, not sent.** The package goes to you and, at your direction, to
+   * your counsel, your insurer or a law-enforcement agency. Decentrys does not
+   * contact counterparties on your behalf unless instructed, and recording
+   * that a package was transmitted is a separate act that names who sent it.
+   *
+   * The document is frozen and hashed at generation, because third parties
+   * make freezing decisions on the strength of these and one that could be
+   * regenerated differently afterwards would be worth nothing. Quote
+   * `contentHash` back to a recipient so they can verify what they hold.
+   */
+  generateEvidencePackage(input: EvidencePackageInput): Promise<EvidencePackage> {
+    return this.request<EvidencePackage>(
+      'POST', `/v1/dri/cases/${encode(input.recoveryCaseId)}/evidence-package`,
+      {
+        recipientType: input.recipientType,
+        recipientName: input.recipientName,
+        ...(input.recoveryLeadId ? { recoveryLeadId: input.recoveryLeadId } : {}),
+      },
+    );
+  }
+
+  // --- transport -----------------------------------------------------------
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    try {
+      const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          'content-type': 'application/json',
+          'x-api-key': this.apiKey,
+          'user-agent': `decentrys-dri/${SDK_VERSION}`,
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        signal: controller.signal,
+      });
+
+      const text = await response.text();
+
+      if (!response.ok) {
+        const parsed = safeParse(text);
+        throw new DriError(
+          response.status,
+          typeof parsed?.message === 'string' ? parsed.message : `Decentrys returned HTTP ${response.status}.`,
+          typeof parsed?.code === 'string' ? parsed.code : undefined,
+        );
+      }
+
+      if (!text) return undefined as T;
+
+      const parsed = safeParse(text);
+      if (parsed === null) throw new DriError(response.status, 'The response was not valid JSON.');
+      return ('data' in parsed ? parsed.data : parsed) as T;
+    } catch (error) {
+      if (error instanceof DriError) throw error;
+      // A disclosure failure is not a transport failure and must not be
+      // rewritten as one — it is thrown by `assertAnalyticalDisclosure`
+      // downstream of this promise, but a caller wrapping the whole call in a
+      // retry would otherwise treat it as a blip and try again forever.
+      if (controller.signal.aborted) throw new DriError(0, `No response within ${this.timeoutMs}ms.`);
+      throw new DriError(0, error instanceof Error ? error.message : 'Request failed.');
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+function encode(segment: string): string {
+  return encodeURIComponent(segment);
+}
+
+function safeParse(text: string): Record<string, unknown> | null {
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveFetch(): FetchLike {
+  const candidate = (globalThis as { fetch?: unknown }).fetch;
+  if (typeof candidate !== 'function') {
+    throw new Error('DRI: no global fetch was found. Pass one via `new DecentrysDri({ fetch })`.');
+  }
+  return candidate.bind(globalThis) as FetchLike;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './model';
+export * from './client';

package/src/model.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import {
+  assertAnalyticalDisclosure, custodialPoints, inferredPoints, MissingDisclosureError,
+  type InterventionAnalysis, type InterventionPoint, type RecoveryIndex,
+} from './model';
+
+function index(overrides: Partial<RecoveryIndex> = {}): RecoveryIndex {
+  return {
+    recoveryCaseId: 'case-1', caseRef: 'REC-2026-0001', incidentRef: 'INC-2026-0007',
+    score: 58, band: 'MODERATE', bandMeaning: 'Value is traceable but sits in non-custodial wallets.',
+    factors: [], modelVersion: 'recovery-outlook-1.0.0', inputsHash: 'abc',
+    computedAt: '2026-02-01T00:00:00.000Z',
+    funnel: {
+      totalLossUsd: 0, byState: {}, locatedUsd: 0, atInterventionPointUsd: 0, freezeRequestedUsd: 0,
+      frozenUsd: 0, recoveredUsd: 0, obfuscatedUsd: 0, lostUsd: 0, untracedUsd: 0,
+      probabilisticUsd: 0, accountedUsd: 0, unaccountedUsd: 0, reconciles: true,
+    },
+    analyticalOnly: true,
+    disclaimer: 'An analytical indicator. Not a probability and not a forecast.',
+    notes: [],
+    ...overrides,
+  };
+}
+
+/**
+ * The Recovery Index is the one number in this product that can be
+ * misunderstood into a promise. Everything else describes what was observed;
+ * this one describes a position, and a position stated without its caveat is
+ * heard as a forecast — by a board, by an insurer, and eventually by whoever
+ * is deciding whether Decentrys said something it should not have.
+ */
+describe('assertAnalyticalDisclosure', () => {
+  it('passes a score that carries both the flag and the text', () => {
+    expect(assertAnalyticalDisclosure(index()).score).toBe(58);
+  });
+
+  it('refuses a score with an empty disclaimer', () => {
+    expect(() => assertAnalyticalDisclosure(index({ disclaimer: '   ' })))
+      .toThrow(MissingDisclosureError);
+  });
+
+  /**
+   * The flag exists because an integrator's code cannot branch on a paragraph.
+   * A payload that carries the prose but not the flag has lost the half that
+   * software can act on, so it fails the same way.
+   */
+  it('refuses a score that is not machine-readably analytical-only', () => {
+    const forged = index({ analyticalOnly: false as unknown as true });
+    expect(() => assertAnalyticalDisclosure(forged)).toThrow(/not marked analytical-only/);
+  });
+
+  it('explains why, rather than just failing', () => {
+    const error = (() => {
+      try { assertAnalyticalDisclosure(index({ disclaimer: '' })); return null; } catch (e) { return e as Error; }
+    })();
+    expect(error!.message).toMatch(/read as a promise of recovery/);
+  });
+});
+
+function point(overrides: Partial<InterventionPoint>): InterventionPoint {
+  return {
+    nodeId: 'n', chain: 'ethereum', address: '0x1', nodeType: 'EXCHANGE', kind: 'CUSTODIAL',
+    label: null, entityName: null, hop: 1, observedPath: true, expanded: false, basis: 'x',
+    ...overrides,
+  };
+}
+
+function analysis(points: InterventionPoint[]): InterventionAnalysis {
+  return {
+    investigationId: 'inv-1', caseRef: 'INV-2026-0001',
+    interventionPoints: points, attributionLimits: [], unexplored: [], notes: [],
+  };
+}
+
+describe('reading an intervention analysis', () => {
+  /**
+   * A custodian holds the value; a bridge operator holds records of value that
+   * has already moved on. Writing this filter by hand at each call site is
+   * exactly where a bridge quietly gets served to counsel as somewhere to send
+   * a freeze request.
+   */
+  it('separates parties that hold value from parties that only have records', () => {
+    const result = custodialPoints(analysis([
+      point({ nodeId: 'cex', kind: 'CUSTODIAL' }),
+      point({ nodeId: 'bridge', kind: 'CROSS_CHAIN', nodeType: 'BRIDGE' }),
+    ]));
+
+    expect(result.map((p) => p.nodeId)).toEqual(['cex']);
+  });
+
+  /**
+   * A list forwarded to counsel must not silently mix destinations that were
+   * traced with destinations that were reasoned to. `inferredPoints` makes the
+   * second set something a caller has to decide about.
+   */
+  it('isolates the points whose connection to the case is inference', () => {
+    const result = inferredPoints(analysis([
+      point({ nodeId: 'traced', observedPath: true }),
+      point({ nodeId: 'post-mixer', observedPath: false }),
+    ]));
+
+    expect(result.map((p) => p.nodeId)).toEqual(['post-mixer']);
+  });
+
+  it('returns nothing rather than everything when a graph has no intervention points', () => {
+    expect(custodialPoints(analysis([]))).toEqual([]);
+    expect(inferredPoints(analysis([]))).toEqual([]);
+  });
+});