@centrifuge/sdk 1.15.3 → 1.17.0

package/dist/utils/poolMetadataMigration.d.ts

@@ -0,0 +1,26 @@
+import { type PoolMetadata, type PoolMetadataV2 } from '../types/poolMetadata.js';
+/**
+ * Pure, idempotent legacy -> v2 migration. Performs no IPFS/network access so it stays
+ * unit-testable. A document already at the current v2 shape is returned unchanged; a v2 document
+ * written by an earlier SDK is normalized forward via {@link upgradeLegacyV2}.
+ *
+ * - Strips fields unused by every consumer (`newInvestmentsStatus`, `reports`, `loanTemplates`,
+ *   `issuer.repName/shortDescription`, onboarding extras) and reshapes `issuer`. `poolRatings` is
+ *   preserved verbatim as a typed field (surfaced via the `ratings` key-fact ref).
+ * - Maps legacy APY modes across `shareClasses[*].apy`.
+ * - Projects the legacy display fields into `pool.factsheet`, and folds the off-chain `holdings`
+ *   blob into a `table` section (`id: 'holdings'`); `holdings` is not carried as a top-level field.
+ */
+export declare function migratePoolMetadataToV2(legacy: PoolMetadata): PoolMetadataV2;
+/**
+ * Hand-rolled structural validator for v2 pool metadata, in the style of
+ * {@link parseMarketplaceCatalog}. Validates the discriminant (`version === 2`), `pool.name`, and
+ * the full `pool.factsheet` content model (the layout the SDK is responsible for). Engine fields
+ * (`shareClasses`, `workflowPolicies`, `addressLabels`, …) are passed through
+ * unchecked here — they are validated where they are consumed (e.g. workflows via
+ * {@link parseMarketplaceCatalog}). Throws `pool metadata v2: …` on the first malformed field;
+ * tolerates missing optionals (visibility defaults to `'public'` app-side). Returns the input
+ * narrowed to {@link PoolMetadataV2} on success.
+ */
+export declare function parsePoolMetadataV2(raw: unknown): PoolMetadataV2;
+//# sourceMappingURL=poolMetadataMigration.d.ts.map

package/dist/utils/poolMetadataMigration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poolMetadataMigration.d.ts","sourceRoot":"","sources":["../../src/utils/poolMetadataMigration.ts"],"names":[],"mappings":"AACA,OAAO,EAeL,KAAK,YAAY,EAEjB,KAAK,cAAc,EAIpB,MAAM,0BAA0B,CAAA;AAoMjC;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAmD5E;AA4XD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAOhE"}

package/dist/utils/poolMetadataMigration.js

@@ -0,0 +1,633 @@
+import { isPoolMetadataV2, } from '../types/poolMetadata.js';
+/* ================================================================================================
+ * Migration: legacy (v1) -> v2
+ * ============================================================================================== */
+/**
+ * Legacy APY display modes that the invest app no longer recognizes, mapped to their nearest v2
+ * equivalent. `target` becomes the hardcoded `fixed` display; the rolling windows pick the 365-day
+ * basis; `automatic` defaults to the 30-day window.
+ */
+const LEGACY_APY_MODE_MAP = {
+    target: 'fixed',
+    '7day': '7d365',
+    '30day': '30d365',
+    '90day': '90d365',
+    automatic: '30d365',
+};
+function migrateApyMode(apy) {
+    if (apy == null)
+        return apy;
+    return LEGACY_APY_MODE_MAP[apy] ?? apy;
+}
+function formatMinInvestment(value) {
+    return value.toLocaleString('en-US');
+}
+/** Tolerates legacy docs that omit (or malform) an array field by treating it as empty. */
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/**
+ * Folds a legacy off-chain `{ headers, data }` holdings blob into a `table` section, preserving
+ * every column verbatim (numbers stay numbers, null/undefined -> '', other values stringified +
+ * trimmed). Returns null when there are no headers or no data.
+ */
+function holdingsTableBlock(holdings) {
+    if (!holdings || !Array.isArray(holdings.headers) || holdings.headers.length === 0 || !Array.isArray(holdings.data)) {
+        return null;
+    }
+    const { headers, data } = holdings;
+    return {
+        type: 'table',
+        id: 'holdings',
+        title: 'Holdings',
+        headers,
+        rows: data.map((row) => headers.map((header) => {
+            const value = row[header];
+            return typeof value === 'number' ? value : value == null ? '' : String(value).trim();
+        })),
+    };
+}
+/** Normalizes an issuer category `type` for matching (case- and separator-insensitive). */
+function normalizeCategoryType(type) {
+    return type.toLowerCase().replace(/[\s_-]/g, '');
+}
+/**
+ * Issuer-category `type` values (normalized) that migrate into the "Service providers" group, mapped
+ * to their v2 display label (the v1 vocabulary differs from v2, e.g. "Sub-Investment Manager" is the
+ * v2 "Portfolio Manager"). Anything not listed stays in "Key facts" with its raw label (the seed is
+ * ops-editable, so an unmatched type is low-cost). `administrator` is an alias of Fund Administrator.
+ */
+const SERVICE_PROVIDER_CATEGORIES = new Map([
+    ['subinvestmentmanager', 'Portfolio Manager'],
+    ['custodian', 'Custodian'],
+    ['fundadministrator', 'Fund Administrator'],
+    ['administrator', 'Fund Administrator'],
+    ['auditor', 'Auditor'],
+]);
+/**
+ * Issuer-category `type` values (normalized) dropped from the factsheet because they are already
+ * represented elsewhere: "Investment Manager" is absorbed by the `Issuer` key fact (from
+ * `issuer.name`), so it is not rendered as its own row.
+ */
+const ABSORBED_CATEGORY_TYPES = new Set(['investmentmanager']);
+/** Document links only carry web/IPFS URIs; anything else (e.g. `javascript:`) is dropped. */
+function isSafeDocumentUri(uri) {
+    const scheme = uri.trim().toLowerCase();
+    return scheme.startsWith('https://') || scheme.startsWith('ipfs://');
+}
+/** Escapes markdown link-breaking characters so an issuer-supplied label can't alter the link. */
+function escapeMarkdownText(text) {
+    return text.replace(/[\\[\]()]/g, '\\$&').replace(/\s+/g, ' ');
+}
+/**
+ * Builds the seed `factsheet` from the legacy display fields. The migration is content-translating:
+ * a migrated pool must render the same content, so legacy fields are projected into ordered key
+ * facts + body blocks. The output is a sensible, ops-editable seed, not a frozen contract.
+ */
+function buildFactsheet(pool, shareClasses, holdings) {
+    const { issuer, asset, poolStructure, expenseRatio, details, poolRatings } = pool;
+    const firstShareClass = Object.values(shareClasses)[0];
+    // Trim text key-fact values (issuer/category strings sometimes carry stray whitespace).
+    const text = (value) => ({ kind: 'text', text: value.trim() });
+    const keyFactItems = [
+        { label: 'Issuer', value: text(issuer.name) },
+        { label: 'Asset type', value: text(`${asset.class} - ${asset.subClass}`) },
+        { label: 'APY', value: { kind: 'ref', ref: 'apy' } },
+        { label: 'Pool structure', value: text(poolStructure) },
+    ];
+    const weightedAverageMaturity = firstShareClass?.weightedAverageMaturity;
+    if (weightedAverageMaturity != null) {
+        keyFactItems.push({ label: 'Average asset maturity', value: text(`${weightedAverageMaturity} days`) });
+    }
+    if (expenseRatio != null && expenseRatio !== '') {
+        keyFactItems.push({ label: 'Expense ratio', value: text(`${expenseRatio}%`) });
+    }
+    const minInitialInvestment = firstShareClass?.minInitialInvestment;
+    if (minInitialInvestment != null) {
+        keyFactItems.push({ label: 'Min. investment', value: text(formatMinInvestment(minInitialInvestment)) });
+    }
+    const serviceProviderItems = [];
+    for (const category of asArray(issuer.categories)) {
+        const key = normalizeCategoryType(category.type);
+        if (ABSORBED_CATEGORY_TYPES.has(key))
+            continue;
+        const label = SERVICE_PROVIDER_CATEGORIES.get(key);
+        if (label) {
+            serviceProviderItems.push({ label, value: text(category.value) });
+        }
+        else {
+            keyFactItems.push({ label: category.type, value: text(category.value) });
+        }
+    }
+    // Seeded unconditionally because v1 has no source field for either: the app derives the deployed
+    // chains, and wallet infrastructure is currently Fordefi for all pools. Ops can edit/remove after.
+    keyFactItems.push({
+        label: 'Wallet infrastructure',
+        value: { kind: 'icons', icons: [{ source: 'app', key: 'fordefi' }] },
+    });
+    keyFactItems.push({ label: 'Available networks', value: { kind: 'ref', ref: 'availableNetworks' } });
+    if (asArray(poolRatings).length > 0) {
+        keyFactItems.push({ label: 'Ratings', value: { kind: 'ref', ref: 'ratings' } });
+    }
+    // Right column is groups only (no bare key facts). The "Service providers" group is added only
+    // when at least one category mapped to it.
+    const keyFacts = [{ type: 'keyFactGroup', id: 'key-facts', title: 'Key facts', items: keyFactItems }];
+    if (serviceProviderItems.length > 0) {
+        keyFacts.push({
+            type: 'keyFactGroup',
+            id: 'service-providers',
+            title: 'Service providers',
+            items: serviceProviderItems,
+        });
+    }
+    const body = [];
+    if (issuer.description) {
+        body.push({ type: 'text', id: 'overview', title: 'Overview', body: issuer.description });
+    }
+    asArray(details).forEach((detail, index) => {
+        body.push({ type: 'text', id: `detail-${index}`, title: detail.title, body: detail.body });
+    });
+    // Ratings reports are surfaced two ways: a Documents body block (markdown links to the report
+    // PDFs) and the `ratings` key-fact ref pill above. Both read the same typed `poolRatings` field.
+    const ratingsWithReports = asArray(poolRatings).filter((rating) => rating.reportFile?.uri && isSafeDocumentUri(rating.reportFile.uri));
+    if (ratingsWithReports.length > 0) {
+        body.push({
+            type: 'text',
+            id: 'documents',
+            title: 'Documents',
+            body: ratingsWithReports
+                .map((rating) => `- [${escapeMarkdownText(rating.agency ?? 'Rating')} rating report](${rating.reportFile.uri})`)
+                .join('\n'),
+        });
+    }
+    body.push({ type: 'section', id: 'performance', ref: 'onchainMetrics' });
+    const holdingsBlock = holdingsTableBlock(holdings);
+    // `sections` is omitted (so the invest app renders its defaults) unless we have a holdings table.
+    return holdingsBlock ? { body, keyFacts, sections: [holdingsBlock] } : { body, keyFacts };
+}
+/**
+ * Pure, idempotent legacy -> v2 migration. Performs no IPFS/network access so it stays
+ * unit-testable. A document already at the current v2 shape is returned unchanged; a v2 document
+ * written by an earlier SDK is normalized forward via {@link upgradeLegacyV2}.
+ *
+ * - Strips fields unused by every consumer (`newInvestmentsStatus`, `reports`, `loanTemplates`,
+ *   `issuer.repName/shortDescription`, onboarding extras) and reshapes `issuer`. `poolRatings` is
+ *   preserved verbatim as a typed field (surfaced via the `ratings` key-fact ref).
+ * - Maps legacy APY modes across `shareClasses[*].apy`.
+ * - Projects the legacy display fields into `pool.factsheet`, and folds the off-chain `holdings`
+ *   blob into a `table` section (`id: 'holdings'`); `holdings` is not carried as a top-level field.
+ */
+export function migratePoolMetadataToV2(legacy) {
+    if (isPoolMetadataV2(legacy))
+        return upgradeLegacyV2(legacy);
+    const { pool, shareClasses, onboarding, merkleProofManager, holdings, addressLabels, workflowPolicies, withdrawManagers, } = legacy;
+    const { issuer, poolRatings, ...restPool } = pool;
+    // Explicitly drop fields that v2 does not carry. `report` (singular) and `poolStatus` are stray
+    // non-schema fields seen in some legacy documents (the real fields are `reports` and `status`).
+    delete restPool.newInvestmentsStatus;
+    delete restPool.reports;
+    delete restPool.details;
+    delete restPool.report;
+    delete restPool.poolStatus;
+    const migratedShareClasses = {};
+    for (const [scId, shareClass] of Object.entries(shareClasses)) {
+        migratedShareClasses[scId] = { ...shareClass, apy: migrateApyMode(shareClass.apy) };
+    }
+    return {
+        version: 2,
+        pool: {
+            ...restPool,
+            issuer: { name: issuer.name, email: issuer.email, logo: issuer.logo },
+            // `poolRatings` stays a typed field verbatim (incl. reportFile); surfaced via the `ratings`
+            // key-fact ref. `holdings` is folded into the factsheet and not carried as a top-level field.
+            poolRatings,
+            factsheet: buildFactsheet(pool, shareClasses, holdings),
+        },
+        shareClasses: migratedShareClasses,
+        ...(merkleProofManager !== undefined ? { merkleProofManager } : {}),
+        ...(onboarding !== undefined
+            ? {
+                onboarding: {
+                    kycRestrictedCountries: onboarding.kycRestrictedCountries,
+                    kybRestrictedCountries: onboarding.kybRestrictedCountries,
+                },
+            }
+            : {}),
+        ...(addressLabels !== undefined ? { addressLabels } : {}),
+        ...(workflowPolicies !== undefined ? { workflowPolicies } : {}),
+        ...(withdrawManagers !== undefined ? { withdrawManagers } : {}),
+    };
+}
+/* ================================================================================================
+ * Intra-v2 upgrade: normalize a v2 document written by an earlier SDK to the current v2 shape
+ * ============================================================================================== */
+function isKeyFactGroup(value) {
+    return typeof value === 'object' && value !== null && value.type === 'keyFactGroup';
+}
+/** Converts an earlier-SDK flat KeyFact (`{ value?: string; valueRef?: 'apy' }`) to the discriminated shape. */
+function upgradeKeyFact(old) {
+    const { value, valueRef, ...rest } = old;
+    let next;
+    if (valueRef === 'apy')
+        next = { kind: 'ref', ref: 'apy' };
+    else if (value !== null && typeof value === 'object' && 'kind' in value)
+        next = value;
+    else
+        next = { kind: 'text', text: typeof value === 'string' ? value : '' };
+    return { ...rest, value: next };
+}
+/** True if `item` is (or, for a tabGroup, contains) a chart still using the `series`/`dataRef` shape. */
+function hasLegacyChart(item) {
+    if (typeof item !== 'object' || item === null)
+        return false;
+    const block = item;
+    if (block.type === 'chart') {
+        return block.data === undefined && (block.series !== undefined || block.dataRef !== undefined);
+    }
+    if (block.type === 'tabGroup' && Array.isArray(block.tabs)) {
+        return block.tabs.some((tab) => hasLegacyChart(tab?.block));
+    }
+    return false;
+}
+/** Converts an earlier-SDK chart block (`series?`/`dataRef?`) to the discriminated `data` field, in place. */
+function upgradeChartBlockInPlace(block) {
+    if (block.type === 'chart' && block.data === undefined) {
+        if (Array.isArray(block.series))
+            block.data = { kind: 'inline', series: block.series };
+        else if (typeof block.dataRef === 'string')
+            block.data = { kind: 'ref', dataRef: block.dataRef };
+        delete block.series;
+        delete block.dataRef;
+    }
+    if (block.type === 'tabGroup' && Array.isArray(block.tabs)) {
+        for (const tab of block.tabs) {
+            const inner = tab?.block;
+            if (inner && typeof inner === 'object')
+                upgradeChartBlockInPlace(inner);
+        }
+    }
+}
+/**
+ * Normalizes a document already at `version: 2` but written by an earlier SDK whose v2 shape differs:
+ * a flat `keyFacts: KeyFact[]` (now `KeyFactGroup[]`), chart blocks with `series`/`dataRef` (now a
+ * discriminated `data`), and a top-level `holdings` blob (now a factsheet `table` section). Without
+ * this, `update()` would re-validate such a document against the current validator and throw, with no
+ * upgrade path. Returns the input unchanged (same reference) when it is already the current shape.
+ */
+function upgradeLegacyV2(doc) {
+    const raw = doc;
+    const pool = (raw.pool ?? {});
+    const factsheet = pool.factsheet;
+    const keyFacts = factsheet?.keyFacts;
+    const layoutItems = [...asArray(factsheet?.body), ...asArray(factsheet?.sections)];
+    const needsKeyFactUpgrade = Array.isArray(keyFacts) && keyFacts.some((item) => !isKeyFactGroup(item));
+    const needsHoldingsFold = raw.holdings != null;
+    const needsChartUpgrade = layoutItems.some(hasLegacyChart);
+    if (!needsKeyFactUpgrade && !needsHoldingsFold && !needsChartUpgrade)
+        return doc;
+    const next = JSON.parse(JSON.stringify(doc));
+    const nextPool = next.pool;
+    const nextFactsheet = nextPool.factsheet;
+    if (nextFactsheet) {
+        if (needsKeyFactUpgrade) {
+            // Wrap the flat list into one titled "Key facts" group, converting each item's value.
+            const items = nextFactsheet.keyFacts.map(upgradeKeyFact);
+            nextFactsheet.keyFacts = [{ type: 'keyFactGroup', id: 'key-facts', title: 'Key facts', items }];
+        }
+        if (needsChartUpgrade) {
+            for (const item of [
+                ...asArray(nextFactsheet.body),
+                ...asArray(nextFactsheet.sections),
+            ]) {
+                if (item && typeof item === 'object')
+                    upgradeChartBlockInPlace(item);
+            }
+        }
+    }
+    if (needsHoldingsFold) {
+        const holdingsBlock = holdingsTableBlock(raw.holdings);
+        delete next.holdings;
+        if (holdingsBlock && nextFactsheet) {
+            nextFactsheet.sections = [...asArray(nextFactsheet.sections), holdingsBlock];
+        }
+    }
+    return next;
+}
+/* ================================================================================================
+ * Validation: hand-rolled structural checks (mirrors src/utils/catalog.ts; no zod dependency)
+ * ============================================================================================== */
+// All enums below are validated as closed sets. The app-owned live-data key registries
+// (`dataRef` / `LiveMetric` / `LiveDataset`) and `section.ref` are PROVISIONAL and expected to grow
+// (see centrifuge/apps-invest#200), but the SDK is the alignment point: an unknown key is rejected
+// on WRITE so the management app, SDK, and invest app stay in sync (adding a key ships in an SDK
+// release). The read path does not validate, so a newer document never breaks an older reader.
+const VISIBILITIES = new Set(['public', 'whitelisted', 'hidden']);
+const CHART_TYPES = new Set(['line', 'area', 'bar', 'donut']);
+const AXIS_FORMATS = new Set(['number', 'percent', 'currency']);
+const XAXIS_TYPES = new Set(['category', 'time', 'number']);
+const DATA_REFS = new Set(['apyVsBenchmarks', 'maturityDistribution']);
+const SECTION_REFS = new Set(['onchainMetrics', 'smartContracts']);
+const LIVE_METRICS = new Set(['tokenPrice', 'nav', 'apy30d', 'navChange', 'monthlyReturn']);
+const LIVE_DATASETS = new Set(['monthlySummary']);
+const KEY_FACT_REFS = new Set(['apy', 'availableNetworks', 'ratings']);
+const COLUMN_FORMATS = new Set(['text', 'number', 'percent', 'currency']);
+const CONTENT_BLOCK_TYPES = new Set(['text', 'table', 'chart', 'image', 'kpiGroup', 'tabGroup', 'liveTable']);
+const TAB_BLOCK_TYPES = new Set(['text', 'table', 'chart', 'kpiGroup']);
+const KPI_TRENDS = new Set(['up', 'down', 'neutral']);
+function fail(message) {
+    throw new Error(`pool metadata v2: ${message}`);
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertString(value, where) {
+    if (typeof value !== 'string')
+        fail(`${where} must be a string`);
+}
+function assertVisibility(value, where) {
+    if (value === undefined)
+        return;
+    if (typeof value !== 'string' || !VISIBILITIES.has(value)) {
+        fail(`${where} has invalid visibility "${String(value)}"`);
+    }
+}
+function isPrimitiveCell(value) {
+    return typeof value === 'string' || typeof value === 'number';
+}
+function validateFile(value, where) {
+    if (!isObject(value))
+        fail(`${where} must be a file object`);
+    assertString(value.uri, `${where}.uri`);
+    assertString(value.mime, `${where}.mime`);
+}
+function validateIconRef(value, where) {
+    if (!isObject(value))
+        fail(`${where} must be an object`);
+    if (value.label !== undefined)
+        assertString(value.label, `${where}.label`);
+    switch (value.source) {
+        case 'metadata':
+            validateFile(value.file, `${where}.file`);
+            if (value.alt !== undefined)
+                assertString(value.alt, `${where}.alt`);
+            break;
+        case 'app':
+            // The app-owned icon-key registry is not yet enumerated, so validate shape (string) only.
+            assertString(value.key, `${where}.key`);
+            break;
+        default:
+            fail(`${where} has an invalid source "${String(value.source)}"`);
+    }
+}
+function validateKeyFactValue(value, where) {
+    if (!isObject(value))
+        fail(`${where} must be an object`);
+    switch (value.kind) {
+        case 'text':
+            assertString(value.text, `${where}.text`);
+            break;
+        case 'icons':
+            if (!Array.isArray(value.icons))
+                fail(`${where}.icons must be an array`);
+            value.icons.forEach((icon, index) => validateIconRef(icon, `${where}.icons[${index}]`));
+            break;
+        case 'ref':
+            // Closed, SDK-enforced registry (extended via a coordinated SDK release).
+            if (typeof value.ref !== 'string' || !KEY_FACT_REFS.has(value.ref)) {
+                fail(`${where}.ref is invalid (unknown ref "${String(value.ref)}")`);
+            }
+            break;
+        default:
+            fail(`${where} has an invalid kind "${String(value.kind)}"`);
+    }
+}
+function validateKeyFact(value, where) {
+    if (!isObject(value))
+        fail(`${where} must be an object`);
+    assertString(value.label, `${where}.label`);
+    validateKeyFactValue(value.value, `${where}.value`);
+    if (value.tooltip !== undefined)
+        assertString(value.tooltip, `${where}.tooltip`);
+    if (value.href !== undefined)
+        assertString(value.href, `${where}.href`);
+    assertVisibility(value.visibility, where);
+}
+function validateKeyFactGroup(value, where) {
+    if (!isObject(value))
+        fail(`${where} must be an object`);
+    if (value.type !== 'keyFactGroup')
+        fail(`${where}.type must be 'keyFactGroup'`);
+    assertString(value.id, `${where}.id`);
+    if (value.title !== undefined)
+        assertString(value.title, `${where}.title`);
+    assertVisibility(value.visibility, where);
+    if (!Array.isArray(value.items))
+        fail(`${where}.items must be an array`);
+    value.items.forEach((item, index) => validateKeyFact(item, `${where}.items[${index}]`));
+}
+function validateChartSeries(value, where) {
+    if (!isObject(value))
+        fail(`${where} must be an object`);
+    assertString(value.name, `${where}.name`);
+    if (value.color !== undefined)
+        assertString(value.color, `${where}.color`);
+    if (!Array.isArray(value.data))
+        fail(`${where}.data must be an array`);
+    value.data.forEach((point, index) => {
+        if (!isObject(point))
+            fail(`${where}.data[${index}] must be an object`);
+        const isCategorical = typeof point.value === 'number' && typeof point.label === 'string';
+        const isXy = (typeof point.x === 'string' || typeof point.x === 'number') && typeof point.y === 'number';
+        if (!isCategorical && !isXy)
+            fail(`${where}.data[${index}] must be {label,value} or {x,y}`);
+    });
+}
+function validateLiveColumn(value, where) {
+    if (!isObject(value))
+        fail(`${where} must be an object`);
+    assertString(value.header, `${where}.header`);
+    if (value.format !== undefined &&
+        (typeof value.format !== 'string' || !COLUMN_FORMATS.has(value.format))) {
+        fail(`${where}.format is invalid`);
+    }
+    assertVisibility(value.visibility, where);
+    switch (value.source) {
+        case 'indexer':
+            if (typeof value.metric !== 'string' || !LIVE_METRICS.has(value.metric)) {
+                fail(`${where} has an invalid indexer metric "${String(value.metric)}"`);
+            }
+            break;
+        case 'hardcoded':
+            assertString(value.key, `${where}.key`);
+            break;
+        case 'static':
+            if (!Array.isArray(value.values) || !value.values.every(isPrimitiveCell)) {
+                fail(`${where}.values must be an array of strings/numbers`);
+            }
+            break;
+        default:
+            fail(`${where} has an invalid source "${String(value.source)}"`);
+    }
+}
+function validateContentBlock(block, type, where) {
+    switch (type) {
+        case 'text':
+            assertString(block.body, `${where}.body`);
+            break;
+        case 'table': {
+            if (!Array.isArray(block.headers) || !block.headers.every((h) => typeof h === 'string')) {
+                fail(`${where}.headers must be an array of strings`);
+            }
+            if (!Array.isArray(block.rows) || !block.rows.every((row) => Array.isArray(row) && row.every(isPrimitiveCell))) {
+                fail(`${where}.rows must be an array of string/number arrays`);
+            }
+            if (block.columnVisibility !== undefined) {
+                if (!Array.isArray(block.columnVisibility))
+                    fail(`${where}.columnVisibility must be an array`);
+                if (block.columnVisibility.length !== block.headers.length) {
+                    fail(`${where}.columnVisibility length must match headers length`);
+                }
+                block.columnVisibility.forEach((v, index) => assertVisibility(v, `${where}.columnVisibility[${index}]`));
+            }
+            break;
+        }
+        case 'chart': {
+            if (typeof block.chartType !== 'string' || !CHART_TYPES.has(block.chartType)) {
+                fail(`${where}.chartType is invalid`);
+            }
+            // Data source is a single discriminated `data` (inline series XOR app/indexer dataRef).
+            if (!isObject(block.data))
+                fail(`${where}.data must be an object`);
+            switch (block.data.kind) {
+                case 'inline':
+                    if (!Array.isArray(block.data.series))
+                        fail(`${where}.data.series must be an array`);
+                    block.data.series.forEach((s, index) => validateChartSeries(s, `${where}.data.series[${index}]`));
+                    break;
+                case 'ref':
+                    // Closed, SDK-enforced registry (extended via a coordinated SDK release).
+                    if (typeof block.data.dataRef !== 'string' || !DATA_REFS.has(block.data.dataRef)) {
+                        fail(`${where}.data.dataRef is invalid (unknown key "${String(block.data.dataRef)}")`);
+                    }
+                    break;
+                default:
+                    fail(`${where}.data has an invalid kind "${String(block.data.kind)}"`);
+            }
+            if (isObject(block.xAxis) && block.xAxis.type !== undefined && !XAXIS_TYPES.has(block.xAxis.type)) {
+                fail(`${where}.xAxis.type is invalid`);
+            }
+            if (isObject(block.yAxis) &&
+                block.yAxis.format !== undefined &&
+                !AXIS_FORMATS.has(block.yAxis.format)) {
+                fail(`${where}.yAxis.format is invalid`);
+            }
+            break;
+        }
+        case 'image':
+            validateFile(block.file, `${where}.file`);
+            break;
+        case 'kpiGroup': {
+            if (block.columns !== undefined && ![1, 2, 3, 4].includes(block.columns)) {
+                fail(`${where}.columns must be 1, 2, 3 or 4`);
+            }
+            if (!Array.isArray(block.items))
+                fail(`${where}.items must be an array`);
+            block.items.forEach((item, index) => {
+                if (!isObject(item))
+                    fail(`${where}.items[${index}] must be an object`);
+                assertString(item.label, `${where}.items[${index}].label`);
+                assertString(item.value, `${where}.items[${index}].value`);
+                if (item.trend !== undefined && !KPI_TRENDS.has(item.trend)) {
+                    fail(`${where}.items[${index}].trend is invalid`);
+                }
+                assertVisibility(item.visibility, `${where}.items[${index}]`);
+            });
+            break;
+        }
+        case 'tabGroup': {
+            if (!Array.isArray(block.tabs))
+                fail(`${where}.tabs must be an array`);
+            block.tabs.forEach((tab, index) => {
+                if (!isObject(tab))
+                    fail(`${where}.tabs[${index}] must be an object`);
+                assertString(tab.label, `${where}.tabs[${index}].label`);
+                if (!isObject(tab.block))
+                    fail(`${where}.tabs[${index}].block must be an object`);
+                const tabBlock = tab.block;
+                if (typeof tabBlock.type !== 'string' || !TAB_BLOCK_TYPES.has(tabBlock.type)) {
+                    fail(`${where}.tabs[${index}].block has an invalid type "${String(tabBlock.type)}"`);
+                }
+                assertString(tabBlock.id, `${where}.tabs[${index}].block.id`);
+                validateContentBlock(tabBlock, tabBlock.type, `${where}.tabs[${index}].block`);
+            });
+            break;
+        }
+        case 'liveTable': {
+            if (typeof block.dataRef !== 'string' || !LIVE_DATASETS.has(block.dataRef)) {
+                fail(`${where}.dataRef is invalid (unknown dataset "${String(block.dataRef)}")`);
+            }
+            if (!Array.isArray(block.columns))
+                fail(`${where}.columns must be an array`);
+            block.columns.forEach((column, index) => validateLiveColumn(column, `${where}.columns[${index}]`));
+            break;
+        }
+        default:
+            fail(`${where} has an unknown block type "${type}"`);
+    }
+}
+function validateLayoutItem(item, where) {
+    if (!isObject(item))
+        fail(`${where} must be an object`);
+    if (typeof item.type !== 'string')
+        fail(`${where} is missing a string \`type\``);
+    assertString(item.id, `${where}.id`);
+    assertVisibility(item.visibility, where);
+    if (item.type === 'section') {
+        if (typeof item.ref !== 'string' || !SECTION_REFS.has(item.ref)) {
+            fail(`${where} has an invalid section ref "${String(item.ref)}"`);
+        }
+        return;
+    }
+    if (!CONTENT_BLOCK_TYPES.has(item.type)) {
+        fail(`${where} has an unknown block type "${item.type}"`);
+    }
+    validateContentBlock(item, item.type, where);
+}
+function validateFactsheet(factsheet) {
+    if (!isObject(factsheet))
+        fail('`pool.factsheet` must be an object');
+    if (!Array.isArray(factsheet.body))
+        fail('`pool.factsheet.body` must be an array');
+    factsheet.body.forEach((item, index) => validateLayoutItem(item, `pool.factsheet.body[${index}]`));
+    if (!Array.isArray(factsheet.keyFacts))
+        fail('`pool.factsheet.keyFacts` must be an array');
+    factsheet.keyFacts.forEach((group, index) => validateKeyFactGroup(group, `pool.factsheet.keyFacts[${index}]`));
+    if (factsheet.sections !== undefined) {
+        if (!Array.isArray(factsheet.sections))
+            fail('`pool.factsheet.sections` must be an array');
+        factsheet.sections.forEach((item, index) => validateLayoutItem(item, `pool.factsheet.sections[${index}]`));
+    }
+}
+/**
+ * Hand-rolled structural validator for v2 pool metadata, in the style of
+ * {@link parseMarketplaceCatalog}. Validates the discriminant (`version === 2`), `pool.name`, and
+ * the full `pool.factsheet` content model (the layout the SDK is responsible for). Engine fields
+ * (`shareClasses`, `workflowPolicies`, `addressLabels`, …) are passed through
+ * unchecked here — they are validated where they are consumed (e.g. workflows via
+ * {@link parseMarketplaceCatalog}). Throws `pool metadata v2: …` on the first malformed field;
+ * tolerates missing optionals (visibility defaults to `'public'` app-side). Returns the input
+ * narrowed to {@link PoolMetadataV2} on success.
+ */
+export function parsePoolMetadataV2(raw) {
+    if (!isObject(raw))
+        fail('expected a JSON object');
+    if (raw.version !== 2)
+        fail(`expected version 2, got ${String(raw.version)}`);
+    if (!isObject(raw.pool))
+        fail('`pool` must be an object');
+    assertString(raw.pool.name, '`pool.name`');
+    if (raw.pool.factsheet !== undefined)
+        validateFactsheet(raw.pool.factsheet);
+    return raw;
+}
+//# sourceMappingURL=poolMetadataMigration.js.map