@oracle-agent/oracle 0.4.1 → 0.4.2

package/src/action-receipts.mjs

@@ -0,0 +1,168 @@
+// Deterministic, public-only receipts for prepared and executed actions.
+//
+// This module deliberately has no authority and no I/O: it does not authorize,
+// sign, broadcast, or fetch. It only records facts supplied by its caller.
+
+import { createHash } from "node:crypto";
+
+export const ACTION_RECEIPT_VERSION = 1;
+
+const SECRET_KEYS = new Set([
+  "privatekey",
+  "mnemonic",
+  "bearer",
+  "authorization",
+  "signature",
+]);
+
+export class ActionReceiptSecretError extends Error {
+  constructor(path) {
+    super(`action receipt refused: secret-bearing field at ${path}`);
+    this.name = "ActionReceiptSecretError";
+    this.code = "ACTION_RECEIPT_SECRET";
+  }
+}
+
+function normalizedKey(key) {
+  return String(key).replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+
+function isSecretKey(key) {
+  const normalized = normalizedKey(key);
+  return [...SECRET_KEYS].some((secret) => normalized.includes(secret));
+}
+
+function publicValue(value, path = "$") {
+  if (value == null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError(`action receipt: non-finite number at ${path}`);
+    return value;
+  }
+  if (typeof value === "bigint") return value.toString();
+  if (Array.isArray(value)) return value.map((item, index) => publicValue(item, `${path}[${index}]`));
+  if (typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new TypeError(`action receipt: JSON-like value required at ${path}`);
+  }
+
+  const out = {};
+  for (const key of Object.keys(value).sort()) {
+    const childPath = `${path}.${key}`;
+    if (isSecretKey(key)) throw new ActionReceiptSecretError(childPath);
+    if (value[key] !== undefined) out[key] = publicValue(value[key], childPath);
+  }
+  return out;
+}
+
+/** Recursively reject secret-bearing fields and return a detached public copy. */
+export function assertNoReceiptSecrets(value) {
+  return publicValue(value);
+}
+
+/** Canonical JSON with recursively sorted object keys. */
+export function canonicalReceiptJson(value) {
+  const safe = publicValue(value);
+  if (safe === null || typeof safe !== "object") return JSON.stringify(safe);
+  if (Array.isArray(safe)) return `[${safe.map(canonicalReceiptJson).join(",")}]`;
+  return `{${Object.keys(safe).map((key) => `${JSON.stringify(key)}:${canonicalReceiptJson(safe[key])}`).join(",")}}`;
+}
+
+/** Hash exactly the public receipt fields, excluding the self-referential id. */
+export function computeReceiptId(receipt) {
+  if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+    throw new TypeError("action receipt: object required");
+  }
+  const { receiptId: _ignored, summary: _derived, ...publicFields } = receipt;
+  return createHash("sha256").update(canonicalReceiptJson(publicFields)).digest("hex");
+}
+
+function supplied(input, ...keys) {
+  for (const key of keys) if (input[key] !== undefined) return input[key];
+  return undefined;
+}
+
+function required(input, keys, label) {
+  const value = supplied(input, ...keys);
+  if (value === undefined || value === null) throw new TypeError(`action receipt: ${label} required`);
+  return value;
+}
+
+function balanceFields(input) {
+  const balances = supplied(input, "balances", "balanceChanges");
+  const before = supplied(input, "beforeBalances", "balancesBefore", "before");
+  const after = supplied(input, "afterBalances", "balancesAfter", "after");
+  if (balances !== undefined) return { balances };
+  if (before === undefined && after === undefined) return {};
+  return { balances: { ...(before === undefined ? {} : { before }), ...(after === undefined ? {} : { after }) } };
+}
+
+/**
+ * Normalize caller-supplied prepare/execute facts into the versioned schema.
+ * Unknown input fields are intentionally omitted from the receipt.
+ */
+export function normalizeActionReceipt(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new TypeError("action receipt: input object required");
+  }
+  // Scan the complete input before selecting fields so a secret cannot be
+  // hidden in an otherwise unknown property and accidentally appear later.
+  publicValue(input);
+
+  const txHash = supplied(input, "txHash", "transactionHash");
+  const phase = supplied(input, "phase", "stage", "resultType") ?? (txHash == null ? "prepare" : "execute");
+  if (phase !== "prepare" && phase !== "execute") {
+    throw new TypeError('action receipt: phase must be "prepare" or "execute"');
+  }
+
+  const fields = {
+    receiptVersion: ACTION_RECEIPT_VERSION,
+    phase,
+    intent: required(input, ["intent"], "intent"),
+    route: required(input, ["route"], "route"),
+    decodedAction: required(input, ["decodedAction", "action"], "decodedAction"),
+    policyChecks: required(input, ["policyChecks", "checks"], "policyChecks"),
+    allowlistHits: required(input, ["allowlistHits", "allowlistMatches"], "allowlistHits"),
+    prepareHash: required(input, ["prepareHash"], "prepareHash"),
+    ...(txHash == null ? {} : { txHash }),
+    ...balanceFields(input),
+  };
+  const receipt = publicValue(fields);
+  return Object.freeze({ ...receipt, receiptId: computeReceiptId(receipt) });
+}
+
+export const createActionReceipt = normalizeActionReceipt;
+
+function label(value, preferred = []) {
+  if (typeof value === "string" || typeof value === "number") return String(value);
+  for (const key of preferred) if (value?.[key] != null) return String(value[key]);
+  return "recorded";
+}
+
+function checkResult(check) {
+  if (typeof check === "boolean") return check;
+  if (check && typeof check === "object") {
+    if (typeof check.ok === "boolean") return check.ok;
+    if (typeof check.allowed === "boolean") return check.allowed;
+    if (typeof check.passed === "boolean") return check.passed;
+  }
+  return null;
+}
+
+/** Produce a compact human-readable statement without changing the receipt. */
+export function summarizeActionReceipt(receipt) {
+  if (!receipt || typeof receipt !== "object") throw new TypeError("action receipt: object required");
+  const action = label(receipt.decodedAction, ["type", "action", "method", "name"]);
+  const route = label(receipt.route, ["name", "provider", "venue", "id"]);
+  const checks = Array.isArray(receipt.policyChecks)
+    ? receipt.policyChecks
+    : Object.values(receipt.policyChecks || {});
+  const passed = checks.filter((check) => checkResult(check) === true).length;
+  const failed = checks.filter((check) => checkResult(check) === false).length;
+  const hits = Array.isArray(receipt.allowlistHits)
+    ? receipt.allowlistHits.length
+    : Object.keys(receipt.allowlistHits || {}).length;
+  const tx = receipt.txHash == null ? "no transaction hash" : `tx ${receipt.txHash}`;
+  const balances = receipt.balances == null ? "balances not provided" : "before/after balances recorded";
+  return `${receipt.phase} ${action} via ${route}; policy ${passed} passed, ${failed} failed; ${hits} allowlist hit${hits === 1 ? "" : "s"}; ${tx}; ${balances}; receipt ${receipt.receiptId}`;
+}
+
+export const formatActionReceipt = summarizeActionReceipt;

package/src/address-book.mjs

@@ -14,6 +14,47 @@ const FORBIDDEN_KEYS = new Set([
   "privatekey", "private_key", "secret", "seed", "mnemonic", "passphrase", "signature", "keystore",
 ]);
 
+// Exact-name matching missed obvious aliases (secretKey, seedPhrase, wif,
+// keyMaterial, xprv...). Match on a normalized key instead: strip separators,
+// lowercase, then look for any secret-ish token as a substring. A label store
+// has no legitimate field containing these words.
+const FORBIDDEN_TOKENS = [
+  "privatekey", "privkey", "secretkey", "secret", "seedphrase", "seed", "mnemonic",
+  "passphrase", "password", "keystore", "keymaterial", "signature", "wif",
+  "xprv", "xpriv", "apikey", "bearer", "credential",
+];
+
+// Key-shaped values must not be persisted even in a free-text field. WIF, xprv,
+// and BIP39 shapes are unambiguous. A bare 64-hex string is NOT — a raw EVM
+// private key and a bytes32 tx hash are byte-identical — so that rule matches
+// only when the WHOLE field is the hex blob. "paid via tx 0xabc..." is a note,
+// not a leaked key.
+const KEY_SHAPED_VALUE = [
+  /\b[5KL][1-9A-HJ-NP-Za-km-z]{50,51}\b/,
+  /\bxprv[0-9A-Za-z]{50,}\b/,
+  /\b(?:[a-z]{3,8}\s+){11,}[a-z]{3,8}\b/i,
+];
+
+const BARE_32_BYTE_HEX = /^\s*(?:0x)?[0-9a-fA-F]{64}\s*$/;
+
+function normalizeKeyName(key) {
+  return String(key).toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function assertNoSecretKeyName(key, path) {
+  const normalized = normalizeKeyName(key);
+  if (FORBIDDEN_KEYS.has(String(key).toLowerCase()) || FORBIDDEN_TOKENS.some((t) => normalized.includes(t))) {
+    throw new Error(`address-book: ${path} is forbidden; the book stores labels, never key material`);
+  }
+}
+
+function assertNoSecretValue(value, path) {
+  if (typeof value !== "string") return;
+  if (KEY_SHAPED_VALUE.some((re) => re.test(value)) || BARE_32_BYTE_HEX.test(value)) {
+    throw new Error(`address-book: ${path} looks like key material; the book stores labels, never key material`);
+  }
+}
+
 export function addressBookPath() {
   const override = env("ORACLE_ADDRESS_BOOK", "MAD_ADDRESS_BOOK", "");
   if (override) return path.resolve(override);
@@ -21,11 +62,18 @@ export function addressBookPath() {
   return path.join(dir, "address-book.json");
 }
 
-function assertNoSecrets(input) {
-  for (const key of Object.keys(input || {})) {
-    if (FORBIDDEN_KEYS.has(key.toLowerCase())) {
-      throw new Error(`address-book: ${key} is forbidden; the book stores labels, never key material`);
-    }
+function assertNoSecrets(input, path = "field") {
+  if (Array.isArray(input)) {
+    input.forEach((item, i) => assertNoSecrets(item, `${path}[${i}]`));
+    return;
+  }
+  if (!input || typeof input !== "object") {
+    assertNoSecretValue(input, path);
+    return;
+  }
+  for (const [key, value] of Object.entries(input)) {
+    assertNoSecretKeyName(key, key);
+    assertNoSecrets(value, key);
   }
 }
 

package/src/exec-policy.mjs

@@ -419,6 +419,12 @@ export function enforceTxPolicy(tx = {}, phase = "broadcast") {
   // Spending caps toggle. Set MAD_VALUE_CAPS_ENABLED=0 in exec.env to lift the
   // per-tx + daily native caps (chain/dest allowlists still enforced). Flip back
   // to 1 to re-arm the cap wall. Default = ON when unset.
+  //
+  // Deliberately strict: ONLY the literal "0" lifts the caps. This is the
+  // opposite polarity from a kill switch. Disabling a kill switch makes a
+  // deployment safer, so it accepts 0/false/off/no. Disabling THIS makes a
+  // deployment riskier, so a stray "false" must keep the cap wall standing
+  // rather than silently removing it. Do not route this through envEnabled.
   const capsOn = String(env("ORACLE_VALUE_CAPS_ENABLED", "MAD_VALUE_CAPS_ENABLED", "1")).trim() !== "0";
   if (!capsOn) return true;
 

package/src/index.mjs

@@ -67,3 +67,27 @@ export {
   DEFAULT_SCOPES,
   normalizeScopes,
 } from "./scopes.mjs";
+
+export { emitHarnessConfigs, createHarnessConfigs } from "./onboarding/harness-configs.mjs";
+export {
+  ACTION_RECEIPT_VERSION,
+  ActionReceiptSecretError,
+  assertNoReceiptSecrets,
+  canonicalReceiptJson,
+  computeReceiptId,
+  normalizeActionReceipt,
+  createActionReceipt,
+  summarizeActionReceipt,
+  formatActionReceipt,
+} from "./action-receipts.mjs";
+export { DEFAULT_RISK_THRESHOLDS, summarizePortfolioRisk, portfolioRiskSummary } from "./portfolio-risk.mjs";
+export {
+  WATCH_CATEGORIES,
+  defaultPreferences,
+  subscribe,
+  unsubscribe,
+  createWatch,
+  evaluateAlert,
+  shouldDeliverAlert,
+} from "./watch-preferences.mjs";
+export { SIGNAL_TYPES, scoreSignals, createSignalsEngine } from "./signals/index.mjs";

package/src/onboarding/harness-configs.mjs

@@ -0,0 +1,102 @@
+const PACKAGE = "@oracle-agent/oracle";
+const COMMAND = "npx";
+const ARGS = ["-y", "--package", PACKAGE, "oracle-data-mcp"];
+const FORBIDDEN_NAME = /(?:^|_)(?:PRIVATE_KEY|SECRET|TOKEN|PASSWORD|PASSPHRASE|MNEMONIC|SEED)(?:_|$)/i;
+
+function requiredText(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${name} must be a non-empty string`);
+  if (/\r|\n|\0/.test(value)) throw new TypeError(`${name} must be a single-line string`);
+  return value.trim();
+}
+
+function validateUrl(value) {
+  const text = requiredText(value, "url");
+  let parsed;
+  try { parsed = new URL(text); } catch { throw new TypeError("url must be a valid http(s) URL"); }
+  if (!/^https?:$/.test(parsed.protocol) || parsed.username || parsed.password) {
+    throw new TypeError("url must be a credential-free http(s) URL");
+  }
+  for (const name of parsed.searchParams.keys()) {
+    if (FORBIDDEN_NAME.test(name) || /^(?:key|api[_-]?key|auth)$/i.test(name)) {
+      throw new TypeError(`url must not contain secret-shaped query parameter: ${name}`);
+    }
+  }
+  return parsed.href;
+}
+
+function validateKey(value) {
+  const text = requiredText(value, "key");
+  if (/^[A-Z][A-Z0-9_]*\s*=/.test(text) || /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(text)) {
+    throw new TypeError("key must be an Oracle agent key, not an environment assignment or private key");
+  }
+  if (/^(?:0x)?[0-9a-f]{64}$/i.test(text) || text.trim().split(/\s+/).length >= 12) {
+    throw new TypeError("key looks like private signing material");
+  }
+  return text;
+}
+
+function validateLabel(value) {
+  const label = requiredText(value, "label");
+  if (!/^[a-z0-9][a-z0-9_-]{0,62}$/i.test(label)) {
+    throw new TypeError("label must contain only letters, digits, underscores, and hyphens");
+  }
+  if (FORBIDDEN_NAME.test(label)) throw new TypeError("label must not be a secret-shaped environment name");
+  return label;
+}
+
+function json(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function yamlString(value) {
+  return JSON.stringify(value);
+}
+
+function tomlString(value) {
+  return JSON.stringify(value);
+}
+
+/**
+ * Return deterministic, copy-pasteable MCP configuration snippets.
+ * This function performs no I/O and never reads from process.env.
+ */
+export function emitHarnessConfigs({ url, key, label = "oracle-data" } = {}) {
+  const endpoint = validateUrl(url);
+  const agentKey = validateKey(key);
+  const name = validateLabel(label);
+  const server = {
+    command: COMMAND,
+    args: [...ARGS],
+    env: { ORACLE_DATA_URL: endpoint, ORACLE_AGENT_KEY: agentKey },
+  };
+  const mcp = { mcpServers: { [name]: server } };
+
+  return {
+    hermes: [
+      "mcp_servers:",
+      `  ${name}:`,
+      `    command: ${yamlString(COMMAND)}`,
+      "    args:",
+      ...ARGS.map((arg) => `      - ${yamlString(arg)}`),
+      "    env:",
+      `      ORACLE_DATA_URL: ${yamlString(endpoint)}`,
+      `      ORACLE_AGENT_KEY: ${yamlString(agentKey)}`,
+      "",
+    ].join("\n"),
+    claudeCode: json(mcp),
+    codex: [
+      `[mcp_servers.${tomlString(name)}]`,
+      `command = ${tomlString(COMMAND)}`,
+      `args = [${ARGS.map(tomlString).join(", ")}]`,
+      "",
+      `[mcp_servers.${tomlString(name)}.env]`,
+      `ORACLE_DATA_URL = ${tomlString(endpoint)}`,
+      `ORACLE_AGENT_KEY = ${tomlString(agentKey)}`,
+      "",
+    ].join("\n"),
+    cursor: json(mcp),
+    genericMcp: json(mcp),
+  };
+}
+
+export const createHarnessConfigs = emitHarnessConfigs;

package/src/oracle-env.mjs

@@ -20,9 +20,18 @@ export function envFlag(primary, legacy, defaultValue = false) {
   return String(env(primary, legacy, fallback)).trim() === "1";
 }
 
+const DISABLE_WORDS = ["0", "false", "off", "no"];
+
+// Reading a flag that may default ON. Only an explicit disable word turns it
+// off, and an unset value keeps `defaultValue`.
+//
+// The old shape (`!== "0"`) inverted with a false default: ORACLE_ONBOARD_HTTP
+// defaults off, so a user writing `false` to keep it off actually ENABLED it,
+// because "false" is not "0". A disable word must never enable a surface.
 export function envEnabled(primary, legacy, defaultValue = true) {
-  const fallback = defaultValue ? "1" : "0";
-  return String(env(primary, legacy, fallback)).trim() !== "0";
+  const raw = String(env(primary, legacy, "")).trim().toLowerCase();
+  if (raw === "") return defaultValue;
+  return !DISABLE_WORDS.includes(raw);
 }
 
 export function csvEnv(primary, legacy) {

package/src/portfolio-risk.mjs

@@ -0,0 +1,170 @@
+// Pure portfolio exposure and coverage summary. This module performs no I/O.
+
+export const DEFAULT_RISK_THRESHOLDS = Object.freeze({
+  assetHighPct: 50,
+  assetMediumPct: 25,
+  chainHighPct: 75,
+  venueHighPct: 60,
+  stablecoinHighPct: 70,
+});
+
+const STABLECOINS = new Set(["USDC", "USDT", "USDT0", "DAI", "FRAX", "LUSD", "TUSD", "USDP", "GUSD", "PYUSD", "USDE"]);
+
+function finite(value) {
+  if (value === null || value === "" || value === undefined) return null;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : null;
+}
+
+function rounded(value) {
+  return Math.round((value + Number.EPSILON) * 1e8) / 1e8;
+}
+
+function pct(value, total) {
+  return total > 0 ? rounded((value / total) * 100) : null;
+}
+
+function addressOf(snapshot) {
+  return snapshot.address || snapshot.owner || snapshot.walletAddress || snapshot.wallet?.address || null;
+}
+
+function labelIndex(labels) {
+  const entries = Array.isArray(labels) ? labels : Array.isArray(labels?.entries) ? labels.entries : [];
+  const index = new Map();
+  for (const entry of entries) {
+    if (!entry?.address) continue;
+    const key = String(entry.address).toLowerCase();
+    if (!index.has(key)) index.set(key, entry);
+  }
+  return index;
+}
+
+function addAsset(output, raw, context = {}) {
+  if (!raw || typeof raw !== "object") return;
+  const symbol = String(raw.symbol ?? raw.coin ?? raw.name ?? raw.collection ?? raw.tokenId ?? "unknown");
+  const value = finite(raw.usdValue ?? raw.valueUsd ?? raw.knownUsd ?? raw.estimatedValueUsd ?? raw.floorValueUsd);
+  const kind = raw.kind === "nft" || raw.type === "nft" || raw.collection || raw.tokenId != null ? "nft" : "fungible";
+  output.push({
+    symbol,
+    usdValue: value,
+    chain: String(raw.chain ?? raw.chainName ?? context.chain ?? "unknown"),
+    venue: String(raw.venue ?? raw.protocol ?? raw.platform ?? context.venue ?? "wallet"),
+    address: raw.address ?? context.address ?? null,
+    kind,
+    stablecoin: raw.stablecoin === true || STABLECOINS.has(symbol.toUpperCase()),
+  });
+}
+
+function assetsFromSnapshot(snapshot) {
+  const output = [];
+  const rootAddress = addressOf(snapshot);
+  for (const asset of snapshot.assets || snapshot.holdings || []) addAsset(output, asset, { address: rootAddress, chain: snapshot.chain, venue: snapshot.venue });
+  for (const chain of snapshot.chains || []) {
+    const chainName = chain.chain ?? chain.name ?? chain.slug ?? (chain.chainId != null ? String(chain.chainId) : chain.family) ?? "unknown";
+    const context = { address: chain.address ?? rootAddress, chain: chainName, venue: chain.venue };
+    if (chain.native && (chain.native.amount == null || Number(chain.native.amount) !== 0)) {
+      addAsset(output, { ...chain.native, symbol: chain.native.symbol ?? chain.symbol ?? chainName }, context);
+    }
+    for (const asset of chain.assets || chain.fungibleTokens?.assets || []) addAsset(output, asset, context);
+    for (const asset of chain.collectibles?.assets || chain.nfts || []) addAsset(output, { ...asset, kind: "nft" }, context);
+    for (const asset of chain.spot?.balances || []) addAsset(output, asset, { ...context, venue: "Hyperliquid spot" });
+    const accountValue = finite(chain.perps?.accountValueUsd);
+    if (accountValue != null) addAsset(output, { symbol: "perps account", usdValue: accountValue }, { ...context, venue: "Hyperliquid perps" });
+  }
+  for (const item of snapshot.inventory?.items || snapshot.nfts?.items || []) addAsset(output, { ...item, kind: "nft" }, { address: rootAddress, chain: item.chain ?? snapshot.chain, venue: item.marketplace ?? snapshot.venue });
+  return output;
+}
+
+function snapshotKey(snapshot, index) {
+  const address = addressOf(snapshot);
+  const chain = snapshot.chain ?? snapshot.chainId ?? snapshot.family ?? "*";
+  return address ? `${String(address).toLowerCase()}|${String(chain).toLowerCase()}` : `snapshot:${index}`;
+}
+
+function buckets(assets, property, total) {
+  const map = new Map();
+  for (const asset of assets) {
+    if (asset.usdValue == null) continue;
+    const name = asset[property];
+    map.set(name, (map.get(name) || 0) + asset.usdValue);
+  }
+  return [...map].map(([name, knownUsd]) => ({ name, knownUsd: rounded(knownUsd), percentOfKnown: pct(knownUsd, total) }))
+    .sort((a, b) => b.knownUsd - a.knownUsd || a.name.localeCompare(b.name));
+}
+
+/**
+ * Summarize already-fetched portfolio snapshots. Accepts either
+ * `{ snapshots, labels, thresholds }` or an array plus an options object.
+ */
+export function summarizePortfolioRisk(input = {}, options = {}) {
+  const snapshots = Array.isArray(input) ? input : Array.isArray(input.snapshots) ? input.snapshots : input.snapshot ? [input.snapshot] : [];
+  const labels = labelIndex(options.labels ?? options.addressBook ?? input.labels ?? input.addressBook);
+  const thresholds = { ...DEFAULT_RISK_THRESHOLDS, ...(input.thresholds || {}), ...(options.thresholds || {}) };
+  const unique = [];
+  const seen = new Set();
+  let duplicatesIgnored = 0;
+  snapshots.forEach((snapshot, index) => {
+    if (!snapshot || typeof snapshot !== "object") return;
+    const key = snapshotKey(snapshot, index);
+    if (seen.has(key)) duplicatesIgnored += 1;
+    else { seen.add(key); unique.push(snapshot); }
+  });
+
+  const assets = unique.flatMap(assetsFromSnapshot);
+  const priced = assets.filter((asset) => asset.usdValue != null);
+  const unknown = assets.filter((asset) => asset.usdValue == null);
+  const explicitUnknown = unique.reduce((sum, snapshot) => sum + Number(snapshot.valuation?.unpricedNonzeroItems || snapshot.unpricedNonzeroItems || 0), 0);
+  const totalKnownUsd = rounded(priced.reduce((sum, asset) => sum + asset.usdValue, 0));
+  const unknownItemCount = unknown.length + explicitUnknown;
+  const chainExposures = buckets(priced, "chain", totalKnownUsd);
+  const venueExposures = buckets(priced, "venue", totalKnownUsd);
+  const groupedAssets = buckets(priced, "symbol", totalKnownUsd);
+  for (const row of chainExposures) row.chain = row.name;
+  for (const row of venueExposures) row.venue = row.name;
+  for (const row of groupedAssets) {
+    row.asset = row.name;
+    row.symbol = row.name;
+  }
+  const stablecoinKnownUsd = rounded(priced.filter((asset) => asset.stablecoin).reduce((sum, asset) => sum + asset.usdValue, 0));
+  const nftAssets = assets.filter((asset) => asset.kind === "nft");
+  const snapshotNftUnvalued = unique.reduce((sum, snapshot) => sum + Number(snapshot.valuation?.nftUnvaluedItems || 0), 0);
+  const nftUnvaluedItems = nftAssets.filter((asset) => asset.usdValue == null).length + snapshotNftUnvalued;
+  const nftValuedItems = nftAssets.filter((asset) => asset.usdValue != null).length;
+  const top = groupedAssets[0] || null;
+  const concentrationLevel = !top ? "unknown" : top.percentOfKnown >= thresholds.assetHighPct ? "high" : top.percentOfKnown >= thresholds.assetMediumPct ? "medium" : "low";
+  const warnings = [];
+  if (unknownItemCount) warnings.push(`${unknownItemCount} nonzero holding(s) have unknown USD value; they are excluded from totals and percentages.`);
+  if (nftUnvaluedItems) warnings.push("NFT valuation coverage is partial; estimates are not executable bids and unvalued NFTs are not treated as zero.");
+  if (duplicatesIgnored) warnings.push(`${duplicatesIgnored} duplicate address/chain snapshot(s) were ignored.`);
+  if (top && concentrationLevel !== "low") warnings.push(`Asset concentration is ${concentrationLevel}: ${top.name} is ${top.percentOfKnown}% of known value.`);
+  if (chainExposures[0]?.percentOfKnown >= thresholds.chainHighPct) warnings.push(`Chain concentration is high: ${chainExposures[0].name} is ${chainExposures[0].percentOfKnown}% of known value.`);
+  if (venueExposures[0]?.percentOfKnown >= thresholds.venueHighPct) warnings.push(`Venue concentration is high: ${venueExposures[0].name} is ${venueExposures[0].percentOfKnown}% of known value.`);
+
+  const addresses = unique.map(addressOf).filter(Boolean).map((address) => {
+    const entry = labels.get(String(address).toLowerCase());
+    return { address, label: entry?.label ?? null, who: entry?.who ?? null, role: entry?.role ?? null };
+  });
+  return {
+    totalKnownUsd,
+    coverage: {
+      complete: unique.length > 0 && unknownItemCount === 0 && unique.every((snapshot) => snapshot.valuation?.complete !== false && snapshot.coverage?.complete !== false),
+      label: unknownItemCount === 0 && unique.length && unique.every((snapshot) => snapshot.valuation?.complete !== false && snapshot.coverage?.complete !== false)
+        ? "complete for the supplied snapshots" : "known priced value only; portfolio coverage is partial or unverified",
+      unknownUsd: unknownItemCount ? null : 0,
+      pricedItemCount: priced.length,
+      unknownItemCount,
+      snapshotCount: unique.length,
+      duplicatesIgnored,
+    },
+    chainExposures,
+    venueExposures,
+    topAssets: groupedAssets.slice(0, Math.max(1, Number(options.topAssets ?? input.topAssets ?? 10))),
+    concentrationRisk: { level: concentrationLevel, topAsset: top?.name ?? null, topAssetPercent: top?.percentOfKnown ?? null, thresholds: { mediumPct: thresholds.assetMediumPct, highPct: thresholds.assetHighPct } },
+    stablecoinExposure: { knownUsd: stablecoinKnownUsd, percentOfKnown: pct(stablecoinKnownUsd, totalKnownUsd), high: totalKnownUsd > 0 && pct(stablecoinKnownUsd, totalKnownUsd) >= thresholds.stablecoinHighPct },
+    nftCoverage: { status: nftAssets.length || snapshotNftUnvalued ? (nftUnvaluedItems ? "partial" : "valued") : "not-observed", valuedItems: nftValuedItems, unvaluedItems: nftUnvaluedItems, knownUsd: rounded(nftAssets.filter((asset) => asset.usdValue != null).reduce((sum, asset) => sum + asset.usdValue, 0)) },
+    addresses,
+    warnings: [...new Set(warnings)],
+  };
+}
+
+export const portfolioRiskSummary = summarizePortfolioRisk;