feat(finance): type source-period and spot identity evidence

apps/presentation/dashboard/smoke/dashboard-coverage-runner.mjs

@@ -0,0 +1,4 @@
+await import("../src/features/personal-workspace/agent-family.test.mjs");
+await import(
+  "../node_modules/.cache/loopx-decision-research-coverage/decision-research-surface-coverage.js"
+);

apps/presentation/dashboard/smoke/decision-research-surface-coverage.tsx

@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import type { DecisionResearchView } from "../src/data/decision-research";
+import {
+  SourcePeriodMetricsCard,
+  SpotMarketIdentityCard,
+} from "../src/views/decision-research-surface";
+
+type SourcePeriodMetric = DecisionResearchView["source_period_metrics"][number];
+type SpotMarketIdentity = NonNullable<DecisionResearchView["spot_market_identity"]>;
+
+const periodMetric: SourcePeriodMetric = {
+  metric_id: "synthetic-fees",
+  label: "Synthetic fees",
+  event_namespace: "synthetic.period.metric",
+  event_id: "event-2026w01",
+  event_at: "2026-01-07T23:00:00Z",
+  instrument_id: "SYNTH-USD",
+  scope_id: "synthetic-scope",
+  period_start: "2026-01-01",
+  period_end: "2026-01-07",
+  source_state: "ok",
+  value: 125,
+  unit: "USD",
+  metric_basis: "period_estimate",
+  metric_semantics: "generic",
+  value_origin: "derived",
+  value_precision: "exact",
+  observation_authority: "derived_exact",
+  sign_basis: "not_signed",
+  fee_inclusion: "not_applicable",
+  account_scope: "not_applicable",
+  account_value_role: "not_applicable",
+  includes_isolated_margin: false,
+  expected_components: ["core", "secondary"],
+  observed_components: ["core"],
+  double_counted_components: ["secondary"],
+  numerator_scope: ["core"],
+  denominator_scope: [],
+  lineage_id: "synthetic-upstream-week",
+  source_ref: "source:synthetic-fees",
+  methodology_state: "verified",
+  anomaly_state: "unverified",
+  event_identity: {
+    namespace: "synthetic.period.metric",
+    source_event_id: "event-2026w01",
+    event_at: "2026-01-07T23:00:00Z",
+    instrument_id: "SYNTH-USD",
+    scope_id: "synthetic-scope",
+  },
+  coverage_state: "partial",
+  missing_components: ["secondary"],
+  lineage_state: "primary",
+  duplicate_of: null,
+  independent_evidence: true,
+  gap_reasons: ["anomaly:unverified"],
+  account_nav_treatment: "not_account_value",
+  ready_eligible: false,
+  admission_reason: "source_period_metric_is_evidence_only",
+};
+
+assert.equal(renderToStaticMarkup(<SourcePeriodMetricsCard metrics={[]} />), "");
+const metricsMarkup = renderToStaticMarkup(
+  <SourcePeriodMetricsCard
+    metrics={[
+      periodMetric,
+      {
+        ...periodMetric,
+        metric_id: "synthetic-missing",
+        period_start: "2026-01-08",
+        period_end: "2026-01-08",
+        value: null,
+        observed_components: [],
+        double_counted_components: [],
+        numerator_scope: [],
+        denominator_scope: ["capital"],
+        coverage_state: "missing",
+        independent_evidence: false,
+        gap_reasons: [],
+      },
+    ]}
+  />,
+);
+assert.match(metricsMarkup, /125 USD/);
+assert.match(metricsMarkup, /2026-01-01 → 2026-01-07/);
+assert.match(metricsMarkup, /missing \(not zero\)/);
+assert.match(metricsMarkup, /Excluded double-counted components:.*secondary/);
+assert.match(metricsMarkup, /Holds:.*anomaly:unverified/);
+assert.match(metricsMarkup, /capital/);
+
+const spotIdentity: SpotMarketIdentity = {
+  pairs: [],
+  tokens: [],
+  contexts: [],
+  markets: [
+    {
+      pair_name: "SYNTH-SPOT",
+      context_coin: "SYNTH-SPOT",
+      base_asset: { index: 3, symbol: "SYN" },
+      quote_asset: { index: 0, symbol: "USDC" },
+      observed_at: "2026-01-15T12:00:00Z",
+      mark_price: 4.25,
+      canonicality: "noncanonical_name",
+      backing_inference: "not_inferred",
+      source_refs: ["source:pair", "source:base", "source:quote", "source:context"],
+      ready_eligible: false,
+    },
+    {
+      pair_name: "MISSING-SPOT",
+      context_coin: "MISSING-SPOT",
+      base_asset: { index: 4, symbol: "MISS" },
+      quote_asset: { index: 0, symbol: "USDC" },
+      observed_at: "2026-01-15T12:00:00Z",
+      mark_price: null,
+      canonicality: "canonical_name",
+      backing_inference: "not_inferred",
+      source_refs: ["source:pair-2", "source:base-2", "source:quote", "source:context-2"],
+      ready_eligible: false,
+    },
+  ],
+};
+
+assert.equal(renderToStaticMarkup(<SpotMarketIdentityCard identity={null} />), "");
+assert.equal(
+  renderToStaticMarkup(<SpotMarketIdentityCard identity={{ ...spotIdentity, markets: [] }} />),
+  "",
+);
+const spotMarkup = renderToStaticMarkup(
+  <SpotMarketIdentityCard identity={spotIdentity} />,
+);
+assert.match(spotMarkup, /SYN \/ USDC/);
+assert.match(spotMarkup, /4.25/);
+assert.match(spotMarkup, /missing \(not zero\)/);
+
+console.log("Decision research source-period rendering coverage passed");

apps/presentation/dashboard/src/data/decision-research.ts

@@ -46,6 +46,145 @@ const researchMetricSchema = z.object({
   tone: researchToneSchema,
 }).strict();
 
+const sourcePeriodMetricSchema = z.object({
+  metric_id: z.string().min(1),
+  label: z.string().min(1),
+  event_namespace: z.string().min(1),
+  event_id: z.string().min(1),
+  event_at: z.string().min(1),
+  instrument_id: z.string().min(1),
+  scope_id: z.string().min(1),
+  period_start: z.string().min(1),
+  period_end: z.string().min(1),
+  source_state: z.enum(["ok", "error"]),
+  value: z.number().finite().nullable(),
+  unit: z.string().min(1),
+  metric_basis: z.enum([
+    "realized_cash",
+    "period_estimate",
+    "annualized_estimate",
+  ]),
+  metric_semantics: z.enum([
+    "generic",
+    "entry_price",
+    "cash_delta",
+    "cumulative_funding_cost",
+    "fill_fee",
+    "account_nav",
+    "account_component",
+    "withdrawable",
+    "external_asset_coverage",
+  ]),
+  value_origin: z.enum(["source_reported", "derived"]),
+  value_precision: z.enum(["exact", "rounded"]),
+  observation_authority: z.enum([
+    "fill_vwap",
+    "source_reported_exact",
+    "derived_exact",
+    "source_reported_rounded",
+    "rounded_position_entry",
+    "derived_rounded",
+  ]),
+  sign_basis: z.enum([
+    "not_signed",
+    "account_cash_change",
+    "funding_cost",
+    "fee_cost",
+  ]),
+  fee_inclusion: z.enum(["not_applicable", "builder_included"]),
+  account_scope: z.enum([
+    "not_applicable",
+    "product",
+    "venue",
+    "unified_account",
+    "external_asset",
+  ]),
+  account_value_role: z.enum([
+    "not_applicable",
+    "nav_owner",
+    "composition",
+    "reconciliation",
+    "withdrawable",
+    "coverage",
+  ]),
+  includes_isolated_margin: z.boolean(),
+  expected_components: z.array(z.string().min(1)).min(1).max(32),
+  observed_components: z.array(z.string().min(1)).max(32),
+  double_counted_components: z.array(z.string().min(1)).max(32),
+  numerator_scope: z.array(z.string().min(1)).max(32),
+  denominator_scope: z.array(z.string().min(1)).max(32),
+  lineage_id: z.string().min(1),
+  source_ref: z.string().min(1),
+  methodology_state: z.enum([
+    "verified",
+    "declared_only",
+    "unverified",
+    "conflicting",
+  ]),
+  anomaly_state: z.enum(["clear", "unverified", "confirmed"]),
+  event_identity: z.object({
+    namespace: z.string().min(1),
+    source_event_id: z.string().min(1),
+    event_at: z.string().min(1),
+    instrument_id: z.string().min(1),
+    scope_id: z.string().min(1),
+  }).strict(),
+  coverage_state: z.enum(["complete", "partial", "missing", "source_error"]),
+  missing_components: z.array(z.string().min(1)).max(32),
+  lineage_state: z.enum(["primary", "duplicate_upstream"]),
+  duplicate_of: z.string().min(1).nullable(),
+  independent_evidence: z.boolean(),
+  gap_reasons: z.array(z.string().min(1)).max(40),
+  account_nav_treatment: z.enum([
+    "authoritative_total",
+    "composition_only",
+    "reconciliation_only",
+    "venue_liquidity_only",
+    "external_asset_coverage_only",
+    "not_account_value",
+  ]),
+  ready_eligible: z.literal(false),
+  admission_reason: z.literal("source_period_metric_is_evidence_only"),
+}).strict();
+
+const spotMarketIdentitySchema = z.object({
+  pairs: z.array(z.object({
+    name: z.string().min(1),
+    asset_indexes: z.array(z.number().int().nonnegative()).length(2),
+    is_canonical: z.boolean(),
+    source_ref: z.string().min(1),
+  }).strict()).max(64),
+  tokens: z.array(z.object({
+    index: z.number().int().nonnegative(),
+    symbol: z.string().min(1),
+    source_ref: z.string().min(1),
+  }).strict()).max(128),
+  contexts: z.array(z.object({
+    coin: z.string().min(1),
+    observed_at: z.string().min(1),
+    mark_price: z.number().finite().positive().nullable(),
+    source_ref: z.string().min(1),
+  }).strict()).max(64),
+  markets: z.array(z.object({
+    pair_name: z.string().min(1),
+    context_coin: z.string().min(1),
+    base_asset: z.object({
+      index: z.number().int().nonnegative(),
+      symbol: z.string().min(1),
+    }).strict(),
+    quote_asset: z.object({
+      index: z.number().int().nonnegative(),
+      symbol: z.string().min(1),
+    }).strict(),
+    observed_at: z.string().min(1),
+    mark_price: z.number().finite().positive().nullable(),
+    canonicality: z.enum(["canonical_name", "noncanonical_name"]),
+    backing_inference: z.literal("not_inferred"),
+    source_refs: z.array(z.string().min(1)).length(4),
+    ready_eligible: z.literal(false),
+  }).strict()).max(64),
+}).strict();
+
 const researchSummarySchema = z.object({
   id: z.string().min(1),
   label: z.string().min(1),
@@ -198,6 +337,8 @@ export const decisionResearchViewSchema = z.object({
     confidence: researchConfidenceSchema,
   }).strict(),
   metrics: z.array(researchMetricSchema).min(1).max(12),
+  source_period_metrics: z.array(sourcePeriodMetricSchema).max(24).optional().default([]),
+  spot_market_identity: spotMarketIdentitySchema.optional(),
   dashboard_summaries: z.array(researchSummarySchema).max(3),
   layers: z.array(researchLayerSchema).min(1).max(12),
   entities: z.array(researchEntitySchema).max(24),