@mapletip/data 0.1.0

package/client/release.js

@@ -0,0 +1,279 @@
+import validateReleaseBuildIndex from '../generated/release-build-index.validator.js';
+import validateReleaseManifest from '../generated/release-manifest.validator.js';
+import validateReleasePin from '../generated/release-pin.validator.js';
+import { minimumPackContractVersion } from './contract-compatibility.mjs';
+import { ScopeError, SchemaValidationError, UnknownBuildError, UnsupportedCapabilityError, UnsupportedProductError, assertCompatibleManifest, assertEnvelopeVersion, createJsonFetcher, isStaticDomain, memoized, normalizedBaseUrl, parsePreloadedJson, productCapability, } from './core.js';
+import { openMonsterProduct } from './monster-client.js';
+function targetCapability(kind) {
+    switch (kind) {
+        case 'monster': return 'monster-core-v1';
+        case 'item': return 'items-v1';
+        case 'equipment': return 'equipment-v1';
+        case 'quest': return 'quests-v1';
+        case 'media': return 'media-v1';
+        case 'map': return 'maps-v1';
+        case 'npc': return 'npcs-v1';
+        case 'reactor': return 'reactors-v1';
+        case 'skill': return 'skills-v1';
+        case 'job': return 'jobs-v1';
+        case 'recipe': return 'recipes-v1';
+        case 'cash-shop': return 'cash-shop-v1';
+        case 'avatar': return 'avatars-v1';
+        default: return undefined;
+    }
+}
+/** Resolve a target against the verified product roster in its build envelope. */
+export function resolveTargetAvailability(build, target) {
+    const capability = targetCapability(target.kind);
+    if (!capability)
+        return 'unknown';
+    return build.productCapabilities.includes(capability) ? 'available' : 'not-available';
+}
+export async function openRelease(options) {
+    if (!validateReleasePin(options.pin)) {
+        throw new SchemaValidationError('pin.json', JSON.stringify(validateReleasePin.errors ?? []));
+    }
+    const baseUrl = normalizedBaseUrl(options.baseUrl);
+    const fetcher = options.fetch ?? globalThis.fetch;
+    const fetchJson = createJsonFetcher({
+        baseUrl,
+        fetcher,
+        onRequest: options.onRequest,
+        signal: options.signal,
+    });
+    const rawManifest = options.preloaded
+        ? await parsePreloadedJson(options.preloaded.releaseManifest, options.pin, 'release-manifest', baseUrl, options.onRequest)
+        : await fetchJson(options.pin, 'release-manifest');
+    if (!validateReleaseManifest(rawManifest)) {
+        throw new SchemaValidationError(options.pin.path, JSON.stringify(validateReleaseManifest.errors ?? []));
+    }
+    const manifest = rawManifest;
+    assertCompatibleManifest(manifest);
+    const minimumVersion = minimumPackContractVersion(manifest);
+    if (!manifest.requiredClientCapabilities.includes('release-manifest-v1')) {
+        throw new UnsupportedCapabilityError('Release manifest does not require release-manifest-v1');
+    }
+    if (manifest.releaseId !== options.pin.releaseId) {
+        throw new ScopeError(`Release manifest ID ${manifest.releaseId} does not match pin ID ${options.pin.releaseId}`);
+    }
+    const rawBuildIndex = options.preloaded
+        ? await parsePreloadedJson(options.preloaded.buildIndex, manifest.buildIndex, 'build-index', baseUrl, options.onRequest)
+        : await fetchJson(manifest.buildIndex, 'build-index');
+    if (!validateReleaseBuildIndex(rawBuildIndex)) {
+        throw new SchemaValidationError(manifest.buildIndex.path, JSON.stringify(validateReleaseBuildIndex.errors ?? []));
+    }
+    const buildIndex = rawBuildIndex;
+    assertEnvelopeVersion(buildIndex.contractVersion, minimumVersion, manifest.buildIndex.path);
+    if (buildIndex.releaseId !== manifest.releaseId) {
+        throw new ScopeError(`Build index release ID ${buildIndex.releaseId} does not match manifest ID ${manifest.releaseId}`);
+    }
+    const builds = [];
+    const buildById = new Map();
+    for (const indexedBuild of buildIndex.builds) {
+        if (indexedBuild.products.length === 0)
+            continue;
+        const rosterCapabilities = [];
+        const seenCapabilities = new Set();
+        let productDescriptor;
+        let monsterProductDescriptor;
+        let itemProductDescriptor;
+        let equipmentProductDescriptor;
+        let mediaProductDescriptor;
+        let questProductDescriptor;
+        const domainProductDescriptors = {};
+        for (const descriptor of indexedBuild.products) {
+            if (descriptor.familyId !== indexedBuild.familyId
+                || descriptor.buildId !== indexedBuild.buildId) {
+                throw new ScopeError(`Product descriptor scope does not match build index entry ${indexedBuild.familyId}/${indexedBuild.buildId}`);
+            }
+            const capability = productCapability(descriptor.productId);
+            if (!capability || (buildIndex.contractVersion === '2.0'
+                && !descriptor.requiredClientCapabilities.includes(capability))) {
+                throw new SchemaValidationError(manifest.buildIndex.path, `Product roster has no matching domain capability for ${descriptor.productId}`);
+            }
+            if (seenCapabilities.has(capability)) {
+                throw new SchemaValidationError(manifest.buildIndex.path, `Product roster repeats capability ${capability} for ${indexedBuild.familyId}/${indexedBuild.buildId}`);
+            }
+            seenCapabilities.add(capability);
+            rosterCapabilities.push(capability);
+            if (capability === 'monster-core-v1') {
+                productDescriptor = descriptor;
+                monsterProductDescriptor = descriptor;
+            }
+            if (capability === 'items-v1')
+                itemProductDescriptor = descriptor;
+            if (capability === 'equipment-v1')
+                equipmentProductDescriptor = descriptor;
+            if (capability === 'media-v1')
+                mediaProductDescriptor = descriptor;
+            if (capability === 'quests-v1')
+                questProductDescriptor = descriptor;
+            const domain = descriptor.productId.slice(0, descriptor.productId.lastIndexOf('-'));
+            if (isStaticDomain(domain))
+                domainProductDescriptors[domain] = descriptor;
+        }
+        rosterCapabilities.sort();
+        if (buildIndex.contractVersion === '2.0' && indexedBuild.productCapabilities === undefined) {
+            throw new ScopeError(`Contract-2.0 build is missing product capabilities for ${indexedBuild.familyId}/${indexedBuild.buildId}`);
+        }
+        if (indexedBuild.productCapabilities !== undefined
+            && (indexedBuild.productCapabilities.length !== rosterCapabilities.length
+                || indexedBuild.productCapabilities.some((capability, index) => capability !== rosterCapabilities[index]))) {
+            throw new SchemaValidationError(manifest.buildIndex.path, `Build product capabilities do not match the shipped product roster for ${indexedBuild.familyId}/${indexedBuild.buildId}`);
+        }
+        const build = {
+            family: indexedBuild.familyId,
+            build: indexedBuild.buildId,
+            productDescriptor,
+            monsterProductDescriptor,
+            itemProductDescriptor,
+            equipmentProductDescriptor,
+            questProductDescriptor,
+            mediaProductDescriptor,
+            domainProductDescriptors,
+            productCapabilities: indexedBuild.productCapabilities ?? rosterCapabilities,
+        };
+        if (buildById.has(build.build)) {
+            throw new SchemaValidationError(manifest.buildIndex.path, `Duplicate build ID: ${build.build}`);
+        }
+        builds.push(build);
+        buildById.set(build.build, build);
+    }
+    function productOptions(build, descriptor) {
+        return {
+            baseUrl,
+            manifest: descriptor.productManifest,
+            expectedScope: { family_id: build.family, build_id: build.build },
+            signal: options.signal,
+            fetch: fetcher,
+            onRequest: options.onRequest,
+        };
+    }
+    function assertDescriptorIdentity(actualProductId, descriptor, label) {
+        if (!actualProductId || actualProductId !== descriptor.productId) {
+            throw new ScopeError(`${label} product manifest identity (${actualProductId ?? 'missing'}) does not match descriptor (${descriptor.productId})`);
+        }
+    }
+    const itemClients = new Map();
+    async function openItemBuild(buildId) {
+        const build = buildById.get(buildId);
+        if (!build)
+            throw new UnknownBuildError(buildId);
+        const descriptor = build.itemProductDescriptor;
+        if (!descriptor) {
+            throw new UnsupportedProductError(`items for build ${buildId}`);
+        }
+        return memoized(itemClients, buildId, async () => {
+            const { openItemProduct } = await import('./items.js');
+            const client = await openItemProduct(productOptions(build, descriptor));
+            if (client.manifest.contractVersion === '2.0' || descriptor.contractVersion === '2.0') {
+                assertDescriptorIdentity(client.manifest.identity?.productId, descriptor, 'Item');
+            }
+            return client;
+        });
+    }
+    const equipmentClients = new Map();
+    async function openEquipmentBuild(buildId) {
+        const build = buildById.get(buildId);
+        if (!build)
+            throw new UnknownBuildError(buildId);
+        const descriptor = build.equipmentProductDescriptor;
+        if (!descriptor) {
+            throw new UnsupportedProductError(`equipment for build ${buildId}`);
+        }
+        return memoized(equipmentClients, buildId, async () => {
+            const { openEquipmentProduct } = await import('./equipment.js');
+            const client = await openEquipmentProduct(productOptions(build, descriptor));
+            if (client.manifest.contractVersion === '2.0' || descriptor.contractVersion === '2.0') {
+                assertDescriptorIdentity(client.manifest.identity?.productId, descriptor, 'Equipment');
+            }
+            return client;
+        });
+    }
+    const productClients = new Map();
+    async function openBuild(buildId) {
+        const build = buildById.get(buildId);
+        if (!build)
+            throw new UnknownBuildError(buildId);
+        const descriptor = build.monsterProductDescriptor ?? build.productDescriptor;
+        if (!descriptor) {
+            throw new UnsupportedProductError(`monsters for build ${buildId}`);
+        }
+        return memoized(productClients, buildId, async () => {
+            const client = await openMonsterProduct(productOptions(build, descriptor));
+            if (client.manifest.contractVersion === '2.0' || descriptor.contractVersion === '2.0') {
+                assertDescriptorIdentity(client.manifest.identity?.productId, descriptor, 'Monster');
+            }
+            return client;
+        });
+    }
+    const mediaClients = new Map();
+    async function openMediaBuild(buildId) {
+        const build = buildById.get(buildId);
+        if (!build)
+            throw new UnknownBuildError(buildId);
+        const descriptor = build.mediaProductDescriptor;
+        if (!descriptor) {
+            throw new UnsupportedProductError(`media for build ${buildId}`);
+        }
+        return memoized(mediaClients, buildId, async () => {
+            const { openMediaProduct } = await import('./media.js');
+            const client = await openMediaProduct(productOptions(build, descriptor));
+            if (client.manifest.contractVersion === '2.0' || descriptor.contractVersion === '2.0') {
+                assertDescriptorIdentity(client.manifest.identity?.productId, descriptor, 'Media');
+            }
+            return client;
+        });
+    }
+    const questClients = new Map();
+    async function openQuestBuild(buildId) {
+        const build = buildById.get(buildId);
+        if (!build)
+            throw new UnknownBuildError(buildId);
+        const descriptor = build.questProductDescriptor;
+        if (!descriptor) {
+            throw new UnsupportedProductError(`quests for build ${buildId}`);
+        }
+        return memoized(questClients, buildId, async () => {
+            const { openQuestProduct } = await import('./quests.js');
+            const client = await openQuestProduct(productOptions(build, descriptor));
+            if (client.manifest.contractVersion === '2.0' || descriptor.contractVersion === '2.0') {
+                assertDescriptorIdentity(client.manifest.identity?.productId, descriptor, 'Quest');
+            }
+            return client;
+        });
+    }
+    const domainClients = new Map();
+    async function openDomainBuild(buildId, domain) {
+        const build = buildById.get(buildId);
+        if (!build)
+            throw new UnknownBuildError(buildId);
+        if (!isStaticDomain(domain))
+            throw new UnsupportedProductError(`${domain} for build ${buildId}`);
+        const descriptor = build.domainProductDescriptors[domain];
+        if (!descriptor)
+            throw new UnsupportedProductError(`${domain} for build ${buildId}`);
+        const cacheKey = `${buildId}:${domain}`;
+        return memoized(domainClients, cacheKey, async () => {
+            const { openStaticDomainProduct } = await import('./static-domains.js');
+            const client = await openStaticDomainProduct(productOptions(build, descriptor));
+            if (client.manifest.productId !== domain) {
+                throw new UnsupportedProductError(String(client.manifest.productId));
+            }
+            if (client.manifest.contractVersion === '2.0' || descriptor.contractVersion === '2.0') {
+                assertDescriptorIdentity(client.manifest.identity?.productId, descriptor, 'Domain');
+            }
+            return client;
+        });
+    }
+    return {
+        manifest,
+        builds,
+        openBuild,
+        openItemBuild,
+        openEquipmentBuild,
+        openMediaBuild,
+        openQuestBuild,
+        openDomainBuild,
+    };
+}

package/client/static-client.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `@mapletip/data` and `@mapletip/data/client` — the broad compatibility entry.
+ *
+ * This barrel re-exports the same implementations that the domain subpaths expose and
+ * adds the legacy generic `openProduct` dispatcher. Consumers that only need one domain
+ * should import `@mapletip/data/monsters`, `/items`, `/equipment`, `/quests`,
+ * `/media` or `/release` instead, which keep the other domains out of the bundle.
+ */
+import { type OpenProductOptions } from './core.js';
+import { type StaticProductClient } from './monster-client.js';
+import { type StaticItemProductClient } from './items.js';
+import { type StaticEquipmentProductClient } from './equipment.js';
+import { type StaticMediaProductClient } from './media.js';
+import { type StaticQuestProductClient } from './quests.js';
+import { type StaticDomainProductClient } from './static-domains.js';
+export { ContractVersionError, IntegrityError, InvalidJsonError, InvalidPathError, MissingPageError, MissingRecordError, RequestError, SchemaValidationError, ScopeError, SecureContextRequiredError, StaticClientError, UnknownBuildError, UnsupportedCapabilityError, UnsupportedProductError, resolveMediaUrl, verifyBlob, } from './core.js';
+export type { GetRelationshipOptions, IntegrityDescriptor, OpenProductOptions, OperationOptions, ProductIdentity, ProductManifestDescriptor, ProductScope, RequestKind, RequestLogEntry, RequestLogHook, StaticProductManifest, } from './core.js';
+export { isMonsterProductClient, openMonsterProduct } from './monster-client.js';
+export type { StaticMonsterCatalog, StaticMonsterDetail, StaticMonsterEvidencePage, StaticProductClient, } from './monster-client.js';
+export { isItemProductClient, openItemProduct } from './items.js';
+export type { StaticItemCatalog, StaticItemDetail, StaticItemProductClient } from './items.js';
+export { isEquipmentProductClient, openEquipmentProduct } from './equipment.js';
+export type { StaticEquipmentCatalog, StaticEquipmentDetail, StaticEquipmentProductClient, } from './equipment.js';
+export { isMediaProductClient, openMediaProduct } from './media.js';
+export type { StaticMediaCatalog, StaticMediaDetail, StaticMediaProductClient } from './media.js';
+export { isQuestProductClient, openQuestProduct } from './quests.js';
+export type { QuestAuxiliaryPack, QuestAuxiliaryPage, QuestBrowsePack, QuestBrowseRecord, QuestCatalog, QuestDetailPack, QuestDetailRecord, QuestEvidencePack, QuestEvidencePage, QuestRelationshipPack, QuestRelationshipRecord, StaticQuestProductClient, } from './quests.js';
+export type { StaticDomainCatalog, StaticDomainCatalogRecord, StaticDomainDetailRecord, StaticDomainFactState, StaticDomainProductClient, StaticDomainSourceIdentity, } from './static-domains.js';
+export { openRelease, resolveTargetAvailability } from './release.js';
+export type { OpenReleaseOptions, ReleaseProductDescriptor, StaticReleaseBuild, StaticReleaseClient, TargetAvailability, } from './release.js';
+export { getMonsterBrowse } from './monsters.js';
+export type { GetMonsterBrowseOptions } from './monsters.js';
+export type AnyProductClient = StaticProductClient | StaticMediaProductClient | StaticQuestProductClient | StaticItemProductClient | StaticEquipmentProductClient | StaticDomainProductClient;
+/**
+ * Open one pinned product of any supported domain.
+ *
+ * The manifest is fetched and verified once, then handed to the matching domain
+ * client. Prefer the domain-specific openers (or `openRelease`) for narrower bundles.
+ */
+export declare function openProduct(options: OpenProductOptions): Promise<AnyProductClient>;

package/client/static-client.js

@@ -0,0 +1,44 @@
+/**
+ * `@mapletip/data` and `@mapletip/data/client` — the broad compatibility entry.
+ *
+ * This barrel re-exports the same implementations that the domain subpaths expose and
+ * adds the legacy generic `openProduct` dispatcher. Consumers that only need one domain
+ * should import `@mapletip/data/monsters`, `/items`, `/equipment`, `/quests`,
+ * `/media` or `/release` instead, which keep the other domains out of the bundle.
+ */
+import { openProductContext, isStaticDomain } from './core.js';
+import { monsterProductClient } from './monster-client.js';
+import { itemProductClient } from './items.js';
+import { equipmentProductClient } from './equipment.js';
+import { mediaProductClient } from './media.js';
+import { questProductClient } from './quests.js';
+import { staticDomainProductClient } from './static-domains.js';
+export { ContractVersionError, IntegrityError, InvalidJsonError, InvalidPathError, MissingPageError, MissingRecordError, RequestError, SchemaValidationError, ScopeError, SecureContextRequiredError, StaticClientError, UnknownBuildError, UnsupportedCapabilityError, UnsupportedProductError, resolveMediaUrl, verifyBlob, } from './core.js';
+export { isMonsterProductClient, openMonsterProduct } from './monster-client.js';
+export { isItemProductClient, openItemProduct } from './items.js';
+export { isEquipmentProductClient, openEquipmentProduct } from './equipment.js';
+export { isMediaProductClient, openMediaProduct } from './media.js';
+export { isQuestProductClient, openQuestProduct } from './quests.js';
+export { openRelease, resolveTargetAvailability } from './release.js';
+export { getMonsterBrowse } from './monsters.js';
+/**
+ * Open one pinned product of any supported domain.
+ *
+ * The manifest is fetched and verified once, then handed to the matching domain
+ * client. Prefer the domain-specific openers (or `openRelease`) for narrower bundles.
+ */
+export async function openProduct(options) {
+    const context = await openProductContext(options);
+    const productId = context.manifest.productId;
+    if (productId === 'items')
+        return itemProductClient(context);
+    if (productId === 'equipment')
+        return equipmentProductClient(context);
+    if (productId === 'media')
+        return mediaProductClient(context);
+    if (productId === 'quests')
+        return questProductClient(context);
+    if (isStaticDomain(productId))
+        return staticDomainProductClient(context);
+    return monsterProductClient(context);
+}

package/client/static-domains.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Static normalized domain products (maps, NPCs, reactors, skills, jobs, recipes,
+ * cash-shop, avatars). These products carry no generated Ajv validators; their
+ * envelopes are checked against the same contract/scope rules as every other pack.
+ */
+import { type OpenProductOptions, type OperationOptions, type ProductScope, type StaticProductManifest, type VerifiedProductContext } from './core.js';
+export type StaticDomainFactState = {
+    readonly state: 'known';
+    readonly value: string;
+} | {
+    readonly state: 'unknown';
+    readonly reason?: string | null;
+} | {
+    readonly state: 'unsupported';
+    readonly capability: string;
+};
+export interface StaticDomainSourceIdentity {
+    readonly namespace?: string;
+    readonly id: string;
+    readonly discriminator?: string;
+}
+export interface StaticDomainCatalogRecord {
+    readonly key: string;
+    readonly sourceIdentity: StaticDomainSourceIdentity;
+    readonly name: StaticDomainFactState;
+    readonly facts: Readonly<Record<string, unknown>>;
+}
+export interface StaticDomainCatalog {
+    readonly format: 'mapletip.domain-catalog/1';
+    readonly contractVersion: string;
+    readonly scope: ProductScope;
+    readonly domain: string;
+    readonly coverage: 'partial';
+    readonly recordCount: number;
+    readonly records: readonly StaticDomainCatalogRecord[];
+}
+export interface StaticDomainDetailRecord extends StaticDomainCatalogRecord {
+    readonly related: Readonly<Record<string, readonly Readonly<Record<string, unknown>>[]>>;
+}
+export interface StaticDomainProductClient {
+    readonly manifest: StaticProductManifest;
+    loadCatalog(options?: OperationOptions): Promise<StaticDomainCatalog>;
+    getDetail(key: string, options?: OperationOptions): Promise<StaticDomainDetailRecord>;
+}
+/** Build a static domain client over an already verified product manifest. */
+export declare function staticDomainProductClient(context: VerifiedProductContext): StaticDomainProductClient;
+/** Open one pinned static domain product. */
+export declare function openStaticDomainProduct(options: OpenProductOptions): Promise<StaticDomainProductClient>;

package/client/static-domains.js

@@ -0,0 +1,113 @@
+/**
+ * Static normalized domain products (maps, NPCs, reactors, skills, jobs, recipes,
+ * cash-shop, avatars). These products carry no generated Ajv validators; their
+ * envelopes are checked against the same contract/scope rules as every other pack.
+ */
+import { MissingRecordError, SchemaValidationError, UnsupportedProductError, assertEnvelopeVersion, assertSameScope, isStaticDomain, memoized, openProductContext, recordRangeDescriptor, } from './core.js';
+function asObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function assertDomainCatalog(value, path, manifest) {
+    const object = asObject(value);
+    const records = object?.records;
+    const scope = asObject(object?.scope);
+    if (!object || object.format !== 'mapletip.domain-catalog/1'
+        || object.contractVersion !== '2.0'
+        || object.domain !== manifest.productId
+        || object.coverage !== 'partial'
+        || !scope || scope.family_id !== manifest.scope.family_id || scope.build_id !== manifest.scope.build_id
+        || !Number.isSafeInteger(object.recordCount)
+        || !Array.isArray(records)
+        || object.recordCount !== records.length) {
+        throw new SchemaValidationError(path, 'invalid MapleKit normalized domain catalog envelope');
+    }
+    let previous = '';
+    for (const recordValue of records) {
+        const record = asObject(recordValue);
+        const source = asObject(record?.sourceIdentity);
+        const name = asObject(record?.name);
+        if (!record || typeof record.key !== 'string' || record.key.length === 0
+            || record.key <= previous || !source || typeof source.id !== 'string'
+            || source.id.length === 0 || !name || typeof record.facts !== 'object'
+            || record.facts === null || Array.isArray(record.facts)) {
+            throw new SchemaValidationError(path, 'invalid or unordered MapleKit domain catalog record');
+        }
+        previous = record.key;
+    }
+    return object;
+}
+function assertDomainDetail(value, path, expectedKey) {
+    const record = asObject(value);
+    const source = asObject(record?.sourceIdentity);
+    const name = asObject(record?.name);
+    const related = asObject(record?.related);
+    if (!record || record.key !== expectedKey || !source || typeof source.id !== 'string'
+        || !name || !related || typeof record.facts !== 'object'
+        || record.facts === null || Array.isArray(record.facts)) {
+        throw new SchemaValidationError(path, 'invalid MapleKit normalized domain detail record');
+    }
+    for (const rows of Object.values(related)) {
+        if (!Array.isArray(rows) || rows.some((row) => !asObject(row))) {
+            throw new SchemaValidationError(path, 'invalid related row graph in MapleKit domain detail');
+        }
+    }
+    return record;
+}
+/** Build a static domain client over an already verified product manifest. */
+export function staticDomainProductClient(context) {
+    const { manifest, fetchJson, minimumVersion } = context;
+    if (!isStaticDomain(manifest.productId))
+        throw new UnsupportedProductError(manifest.productId);
+    let catalogPromise;
+    const detailPackCache = new Map();
+    async function loadCatalog(operation) {
+        if (!catalogPromise) {
+            catalogPromise = (async () => {
+                const raw = await fetchJson(manifest.catalog, 'catalog', operation);
+                assertEnvelopeVersion(raw.contractVersion, minimumVersion, manifest.catalog.path);
+                const catalog = assertDomainCatalog(raw, manifest.catalog.path, manifest);
+                assertSameScope(catalog.scope, manifest.scope, manifest.catalog.path);
+                if (catalog.records.length !== catalog.recordCount) {
+                    throw new SchemaValidationError(manifest.catalog.path, 'recordCount does not match records length');
+                }
+                return catalog;
+            })();
+            void catalogPromise.catch(() => { catalogPromise = undefined; });
+        }
+        return catalogPromise;
+    }
+    async function getDetail(key, operation) {
+        const descriptor = recordRangeDescriptor(manifest.detailPacks, key, 'detail', manifest.productId);
+        const pack = await memoized(detailPackCache, descriptor.path, async () => {
+            const raw = await fetchJson(descriptor, 'detail', operation);
+            const envelope = asObject(raw);
+            if (!envelope || envelope.format !== 'mapletip.domain-detail-pack/1'
+                || envelope.contractVersion !== '2.0'
+                || envelope.domain !== manifest.productId
+                || !envelope.scope || JSON.stringify(envelope.scope) !== JSON.stringify(manifest.scope)) {
+                throw new SchemaValidationError(descriptor.path, 'invalid MapleKit normalized domain detail pack envelope');
+            }
+            assertEnvelopeVersion(envelope.contractVersion, minimumVersion, descriptor.path);
+            const records = asObject(envelope.records);
+            if (!records || Object.keys(records).length !== descriptor.count) {
+                throw new SchemaValidationError(descriptor.path, 'detail pack count does not match its descriptor');
+            }
+            const normalized = {};
+            for (const [recordKey, recordValue] of Object.entries(records)) {
+                normalized[recordKey] = assertDomainDetail(recordValue, descriptor.path, recordKey);
+            }
+            return normalized;
+        });
+        const detail = pack[key];
+        if (!detail)
+            throw new MissingRecordError(key, manifest.productId);
+        return detail;
+    }
+    return { manifest, loadCatalog, getDetail };
+}
+/** Open one pinned static domain product. */
+export async function openStaticDomainProduct(options) {
+    return staticDomainProductClient(await openProductContext(options));
+}

package/generated/contract-2-catalog-fact.d.ts

@@ -0,0 +1,51 @@
+/* Generated automatically from Rust-owned wire definitions. Do not edit. */
+
+/**
+ * Compact catalog projection of [`FactState`]. It keeps the state and a
+ * positively observed value, retains the coverage witness for `absent`, and
+ * omits source attribution and explanatory metadata.
+ */
+export type CatalogFact<T = RawScalar> =
+  | {
+      state: "known";
+      value: T;
+    }
+  | {
+      state: "unknown";
+    }
+  | {
+      coverageKey: CoverageKey;
+      state: "absent";
+    }
+  | {
+      state: "unsupported";
+    };
+/**
+ * A scalar source observation that preserves the source value kind.
+ */
+export type RawScalar =
+  | {
+      kind: "integer";
+      value: SafeInt64;
+    }
+  | {
+      kind: "real";
+      value: number;
+    }
+  | {
+      kind: "text";
+      value: string;
+    }
+  | {
+      kind: "boolean";
+      value: boolean;
+    }
+  | {
+      kind: "bytes";
+      value: number[];
+    }
+  | {
+      kind: "source-null";
+    };
+export type SafeInt64 = number;
+export type CoverageKey = string;