@vmz/vmz 0.0.0 → 0.0.2

package/dist/locale-runtime.js

@@ -0,0 +1,542 @@
+// @ts-nocheck
+/**
+ * Locale I2 runtime: LocaleContext · FormatterContext · negotiation ·
+ * atomic LocaleTransition · SSR/client parity.
+ * Design: 规划设计/vmz/28 §5–§8
+ *
+ * Not an I18n IR — ApplicationContext + Delivery projections over VPG Message views.
+ */
+import { createHash } from 'node:crypto';
+import { DIAG_FORMATTER_CONTEXT_INCOMPLETE, DIAG_FORMATTER_VERSION_MISMATCH, DIAG_LOCALE_DIGEST_MISMATCH, DIAG_LOCALE_MACHINE_DEFAULT_FORBIDDEN, DIAG_LOCALE_STALE_GENERATION, DIAG_LOCALE_TRANSITION_LOAD_FAILED, DIAG_LOCALE_TRANSITION_PARTIAL, DIAG_LOCALE_TRANSITION_UNSUPPORTED, DIAG_MESSAGE_MIXED_LOCALE, FORMATTER_DATA_VERSION, LOCALE_APPLICATION_CONTEXT_SCHEMA, LOCALE_FALLBACK_RESOLUTION_SCHEMA, LOCALE_FORMATTER_CONTEXT_SCHEMA, LOCALE_RUNTIME_CHECK_SCHEMA, LOCALE_TRANSITION_SCHEMA, } from './locale-schema.js';
+/**
+ * Fixed negotiation priority (doc 28 §6). Host only supplies candidates.
+ * @param {{
+ *   supportedLocales: string[],
+ *   defaultLocale: string,
+ *   routeLocale?: string|null,
+ *   userChoice?: string|null,
+ *   preference?: string|null,
+ *   hostCandidates?: string[],
+ * }} input
+ */
+export function negotiateLocale(input) {
+    const supported = new Set(input.supportedLocales || []);
+    /** @param {string|null|undefined} id */
+    const accept = (id) => {
+        if (!id || typeof id !== 'string')
+            return null;
+        // Exact LocaleId only — no zh-TW → zh-hant guessing.
+        return supported.has(id) ? id : null;
+    };
+    return (accept(input.routeLocale) ||
+        accept(input.userChoice) ||
+        accept(input.preference) ||
+        (input.hostCandidates || []).map(accept).find(Boolean) ||
+        input.defaultLocale);
+}
+/**
+ * @param {{
+ *   applicationId: string,
+ *   deliveryId: string,
+ *   localeId: string,
+ *   timeZone: string,
+ *   calendar?: string,
+ *   numberingSystem?: string,
+ *   direction?: string,
+ *   generation?: number,
+ * }} opts
+ */
+export function buildApplicationContext(opts) {
+    return {
+        schema: LOCALE_APPLICATION_CONTEXT_SCHEMA,
+        applicationId: opts.applicationId,
+        deliveryId: opts.deliveryId,
+        localeId: opts.localeId,
+        timeZone: opts.timeZone,
+        calendar: opts.calendar ?? 'gregory',
+        numberingSystem: opts.numberingSystem ?? 'latn',
+        direction: opts.direction ?? 'ltr',
+        generation: opts.generation ?? 1,
+    };
+}
+/**
+ * @param {ReturnType<typeof buildApplicationContext>} app
+ * @param {{ currency?: string }} [opts]
+ */
+export function buildFormatterContext(app, opts = {}) {
+    return {
+        schema: LOCALE_FORMATTER_CONTEXT_SCHEMA,
+        localeId: app.localeId,
+        timeZone: app.timeZone,
+        calendar: app.calendar || 'gregory',
+        numberingSystem: app.numberingSystem || 'latn',
+        currency: opts.currency ?? null,
+        formatterDataVersion: FORMATTER_DATA_VERSION,
+    };
+}
+/**
+ * Stable digest for Resume / SSR↔client parity.
+ * @param {ReturnType<typeof buildFormatterContext>} formatter
+ */
+export function formatterContextDigest(formatter) {
+    const canonical = {
+        schema: formatter.schema,
+        localeId: formatter.localeId,
+        timeZone: formatter.timeZone,
+        calendar: formatter.calendar,
+        numberingSystem: formatter.numberingSystem,
+        currency: formatter.currency ?? null,
+        formatterDataVersion: formatter.formatterDataVersion,
+    };
+    return createHash('sha256').update(JSON.stringify(canonical)).digest('hex').slice(0, 32);
+}
+/**
+ * Server must not read machine locale/timezone defaults.
+ * @param {ReturnType<typeof buildFormatterContext>} formatter
+ * @param {{ allowMachineDefault?: boolean }} [opts]
+ */
+export function validateFormatterContext(formatter, opts = {}) {
+    /** @type {Array<{code:string,severity:string,message:string}>} */
+    const diagnostics = [];
+    if (!formatter?.localeId || !formatter?.timeZone) {
+        diagnostics.push({
+            code: DIAG_FORMATTER_CONTEXT_INCOMPLETE,
+            severity: 'error',
+            message: 'FormatterContext requires localeId and timeZone',
+        });
+    }
+    if (!formatter?.calendar || !formatter?.numberingSystem) {
+        diagnostics.push({
+            code: DIAG_FORMATTER_CONTEXT_INCOMPLETE,
+            severity: 'error',
+            message: 'FormatterContext requires calendar and numberingSystem',
+        });
+    }
+    if (formatter?.formatterDataVersion && formatter.formatterDataVersion !== FORMATTER_DATA_VERSION) {
+        diagnostics.push({
+            code: DIAG_FORMATTER_VERSION_MISMATCH,
+            severity: 'error',
+            message: `formatterDataVersion ${formatter.formatterDataVersion} != ${FORMATTER_DATA_VERSION}`,
+        });
+    }
+    if (!opts.allowMachineDefault) {
+        const tz = String(formatter?.timeZone || '');
+        if (!tz || tz === 'local' || tz === 'system' || tz === 'Etc/Unknown') {
+            diagnostics.push({
+                code: DIAG_LOCALE_MACHINE_DEFAULT_FORBIDDEN,
+                severity: 'error',
+                message: `server FormatterContext forbids machine timezone ${JSON.stringify(tz)}`,
+            });
+        }
+    }
+    return {
+        ok: diagnostics.length === 0,
+        diagnostics,
+    };
+}
+/**
+ * Resolve one MessageBinding to a single locale variant (whole-message, no mix).
+ * @param {{
+ *   messageId: string,
+ *   requestedLocale: string,
+ *   variants: Record<string, { template: string }>,
+ *   fallback?: Record<string, string[]>,
+ * }} input
+ */
+export function resolveMessageVariant(input) {
+    const fallback = input.fallback || {};
+    const chain = [input.requestedLocale, ...(fallback[input.requestedLocale] || [])];
+    for (const loc of chain) {
+        const variant = input.variants?.[loc];
+        if (variant?.template != null) {
+            return {
+                schema: LOCALE_FALLBACK_RESOLUTION_SCHEMA,
+                messageId: input.messageId,
+                requestedLocale: input.requestedLocale,
+                resolvedLocale: loc,
+                fallbackPath: chain.slice(0, chain.indexOf(loc) + 1),
+                template: variant.template,
+                ok: true,
+            };
+        }
+    }
+    return {
+        schema: LOCALE_FALLBACK_RESOLUTION_SCHEMA,
+        messageId: input.messageId,
+        requestedLocale: input.requestedLocale,
+        resolvedLocale: null,
+        fallbackPath: chain,
+        template: null,
+        ok: false,
+    };
+}
+/**
+ * Minimal ICU MessageFormat subset for I2 parity proofs (params + plural + #).
+ * @param {string} template
+ * @param {Record<string, any>} [args]
+ */
+export function formatMessageTemplate(template, args = {}) {
+    let text = String(template || '');
+    // plural / selectordinal / select blocks first
+    text = text.replace(/\{(\w+),\s*(plural|selectordinal|select)\s*,\s*((?:[^={}]+\{[^{}]*\}\s*)+)\}/g, (_m, name, _kind, body) => {
+        const n = Number(args[name]);
+        const pick = (key) => {
+            const re = new RegExp(`${key}\\s*\\{([^{}]*)\\}`);
+            const hit = body.match(re);
+            return hit ? hit[1] : null;
+        };
+        let branch = null;
+        if (Number.isFinite(n) && Object.hasOwn(args, name)) {
+            branch = pick(`=${n}`) || (n === 1 ? pick('one') : null) || pick('other');
+        }
+        else {
+            branch = pick(String(args[name])) || pick('other');
+        }
+        if (branch == null)
+            return _m;
+        return branch.replace(/#/g, String(Number.isFinite(n) ? n : (args[name] ?? '')));
+    });
+    text = text.replace(/\{(\w+)(?:,\s*\w+)?\}/g, (_m, name) => {
+        if (Object.hasOwn(args, name))
+            return String(args[name]);
+        return _m;
+    });
+    return text;
+}
+/**
+ * @param {{
+ *   applicationId: string,
+ *   deliveryId: string,
+ *   supportedLocales: string[],
+ *   defaultLocale: string,
+ *   fallback?: Record<string, string[]>,
+ *   directions?: Record<string, string>,
+ *   messages: Record<string, { variants: Record<string, { template: string }> }>,
+ *   initialLocaleId: string,
+ *   timeZone: string,
+ *   generation?: number,
+ *   loadedChunks?: Set<string>|string[],
+ * }} opts
+ */
+export function createLocaleSession(opts) {
+    const supported = new Set(opts.supportedLocales);
+    const directions = opts.directions || {};
+    const fallback = opts.fallback || {};
+    let generation = opts.generation ?? 1;
+    /** @type {Set<string>} */
+    const loaded = new Set(opts.loadedChunks || [opts.initialLocaleId]);
+    let app = buildApplicationContext({
+        applicationId: opts.applicationId,
+        deliveryId: opts.deliveryId,
+        localeId: opts.initialLocaleId,
+        timeZone: opts.timeZone,
+        direction: directions[opts.initialLocaleId] || 'ltr',
+        generation,
+    });
+    let formatter = buildFormatterContext(app);
+    let digest = formatterContextDigest(formatter);
+    function snapshot() {
+        return {
+            applicationContext: { ...app },
+            formatterContext: { ...formatter },
+            formatterDigest: digest,
+            loadedChunks: [...loaded],
+            generation,
+        };
+    }
+    /**
+     * Render all known messages under current locale (atomic surface proof).
+     * @param {Record<string, Record<string, any>>} [argMap]
+     */
+    function renderAll(argMap = {}) {
+        /** @type {Record<string, { text: string, resolvedLocale: string }>} */
+        const out = {};
+        /** @type {string[]} */
+        const resolvedLocales = [];
+        for (const [messageId, node] of Object.entries(opts.messages)) {
+            const res = resolveMessageVariant({
+                messageId,
+                requestedLocale: app.localeId,
+                variants: node.variants,
+                fallback,
+            });
+            if (!res.ok)
+                continue;
+            out[messageId] = {
+                text: formatMessageTemplate(res.template, argMap[messageId] || {}),
+                resolvedLocale: res.resolvedLocale,
+            };
+            resolvedLocales.push(res.resolvedLocale);
+        }
+        const unique = [...new Set(resolvedLocales)];
+        return { bindings: out, resolvedLocales: unique };
+    }
+    /**
+     * Atomic LocaleTransition (doc 28 §5).
+     * @param {string} targetLocaleId
+     * @param {{
+     *   generation?: number,
+     *   loadChunk?: (localeId: string) => boolean|Promise<boolean>,
+     *   timeZone?: string,
+     * }} [transitionOpts]
+     */
+    async function transition(targetLocaleId, transitionOpts = {}) {
+        const fromLocale = app.localeId;
+        const expectedGen = transitionOpts.generation ?? generation;
+        if (expectedGen !== generation) {
+            return {
+                schema: LOCALE_TRANSITION_SCHEMA,
+                status: 'cancelled',
+                fromLocale,
+                toLocale: targetLocaleId,
+                reason: 'stale_generation',
+                diagnostics: [
+                    {
+                        code: DIAG_LOCALE_STALE_GENERATION,
+                        severity: 'error',
+                        message: `transition generation ${expectedGen} != session ${generation}`,
+                    },
+                ],
+                snapshot: snapshot(),
+            };
+        }
+        if (!supported.has(targetLocaleId)) {
+            return {
+                schema: LOCALE_TRANSITION_SCHEMA,
+                status: 'rejected',
+                fromLocale,
+                toLocale: targetLocaleId,
+                reason: 'unsupported',
+                diagnostics: [
+                    {
+                        code: DIAG_LOCALE_TRANSITION_UNSUPPORTED,
+                        severity: 'error',
+                        message: `LocaleId ${targetLocaleId} not in supportedLocales`,
+                    },
+                ],
+                snapshot: snapshot(),
+            };
+        }
+        let loadOk = true;
+        if (typeof transitionOpts.loadChunk === 'function') {
+            try {
+                loadOk = Boolean(await transitionOpts.loadChunk(targetLocaleId));
+            }
+            catch {
+                loadOk = false;
+            }
+        }
+        else if (!loaded.has(targetLocaleId)) {
+            // Without a loader, missing chunk cannot commit.
+            loadOk = false;
+        }
+        if (!loadOk) {
+            return {
+                schema: LOCALE_TRANSITION_SCHEMA,
+                status: 'rolled_back',
+                fromLocale,
+                toLocale: targetLocaleId,
+                reason: 'load_failed',
+                diagnostics: [
+                    {
+                        code: DIAG_LOCALE_TRANSITION_LOAD_FAILED,
+                        severity: 'error',
+                        message: `locale chunk ${targetLocaleId} failed to load; keeping ${fromLocale}`,
+                    },
+                ],
+                snapshot: snapshot(),
+            };
+        }
+        // Commit only after resources are ready — single transaction.
+        loaded.add(targetLocaleId);
+        generation += 1;
+        app = buildApplicationContext({
+            applicationId: opts.applicationId,
+            deliveryId: opts.deliveryId,
+            localeId: targetLocaleId,
+            timeZone: transitionOpts.timeZone || opts.timeZone,
+            direction: directions[targetLocaleId] || 'ltr',
+            generation,
+        });
+        formatter = buildFormatterContext(app);
+        digest = formatterContextDigest(formatter);
+        const rendered = renderAll();
+        // After commit, every binding must resolve under the new requested locale
+        // (or its explicit fallback chain) — never a mix of independent "half pages".
+        const foreign = rendered.resolvedLocales.filter((loc) => loc !== targetLocaleId && !(fallback[targetLocaleId] || []).includes(loc));
+        /** @type {any[]} */
+        const diagnostics = [];
+        if (foreign.length) {
+            diagnostics.push({
+                code: DIAG_MESSAGE_MIXED_LOCALE,
+                severity: 'error',
+                message: `post-transition mixed locales: ${foreign.join(',')}`,
+            });
+            diagnostics.push({
+                code: DIAG_LOCALE_TRANSITION_PARTIAL,
+                severity: 'error',
+                message: 'LocaleTransition produced a partial language surface',
+            });
+        }
+        return {
+            schema: LOCALE_TRANSITION_SCHEMA,
+            status: diagnostics.length ? 'failed' : 'committed',
+            fromLocale,
+            toLocale: targetLocaleId,
+            reason: diagnostics.length ? 'partial' : 'ok',
+            diagnostics,
+            snapshot: snapshot(),
+            rendered,
+        };
+    }
+    return {
+        negotiateLocale,
+        snapshot,
+        renderAll,
+        transition,
+        get applicationContext() {
+            return { ...app };
+        },
+        get formatterContext() {
+            return { ...formatter };
+        },
+        get formatterDigest() {
+            return digest;
+        },
+    };
+}
+/**
+ * SSR and client must share the same resolved FormatterContext digest and texts.
+ * @param {{
+ *   ssr: { localeId: string, formatterDigest: string, formatterDataVersion?: string, texts: Record<string, string> },
+ *   client: { localeId: string, formatterDigest: string, formatterDataVersion?: string, texts: Record<string, string> },
+ * }} input
+ */
+export function checkSsrClientParity(input) {
+    /** @type {Array<{code:string,severity:string,message:string}>} */
+    const diagnostics = [];
+    const { ssr, client } = input;
+    if (ssr.localeId !== client.localeId) {
+        diagnostics.push({
+            code: DIAG_LOCALE_DIGEST_MISMATCH,
+            severity: 'error',
+            message: `localeId SSR ${ssr.localeId} != client ${client.localeId}`,
+        });
+    }
+    if (ssr.formatterDigest !== client.formatterDigest) {
+        diagnostics.push({
+            code: DIAG_LOCALE_DIGEST_MISMATCH,
+            severity: 'error',
+            message: `formatterDigest SSR ${ssr.formatterDigest} != client ${client.formatterDigest}`,
+        });
+    }
+    const ssrVer = ssr.formatterDataVersion || FORMATTER_DATA_VERSION;
+    const clientVer = client.formatterDataVersion || FORMATTER_DATA_VERSION;
+    if (ssrVer !== clientVer) {
+        diagnostics.push({
+            code: DIAG_FORMATTER_VERSION_MISMATCH,
+            severity: 'error',
+            message: `formatterDataVersion SSR ${ssrVer} != client ${clientVer}`,
+        });
+    }
+    const keys = new Set([...Object.keys(ssr.texts || {}), ...Object.keys(client.texts || {})]);
+    for (const k of keys) {
+        if ((ssr.texts || {})[k] !== (client.texts || {})[k]) {
+            diagnostics.push({
+                code: DIAG_LOCALE_DIGEST_MISMATCH,
+                severity: 'error',
+                message: `text mismatch for ${k}: SSR=${JSON.stringify((ssr.texts || {})[k])} client=${JSON.stringify((client.texts || {})[k])}`,
+            });
+        }
+    }
+    return {
+        schema: LOCALE_RUNTIME_CHECK_SCHEMA,
+        status: diagnostics.length ? 'failed' : 'ready',
+        kind: 'ssr_client_parity',
+        diagnostics,
+    };
+}
+/**
+ * Aggregate I2 runtime proof for a project check report + explicit contexts.
+ * @param {{
+ *   manifest: { defaultLocale: string, locales: Array<{id:string,direction?:string}>, fallback?: Record<string,string[]> },
+ *   messages: Array<{ messageId: string, variants: Record<string, { template: string }> }>,
+ *   applicationId?: string,
+ *   deliveryId?: string,
+ *   timeZone?: string,
+ * }} input
+ */
+export function checkLocaleRuntime(input) {
+    /** @type {any[]} */
+    const diagnostics = [];
+    const supported = (input.manifest?.locales || []).map((l) => l.id);
+    const defaultLocale = input.manifest?.defaultLocale;
+    const fallback = input.manifest?.fallback || {};
+    const directions = Object.fromEntries((input.manifest?.locales || []).map((l) => [l.id, l.direction || 'ltr']));
+    /** @type {Record<string, { variants: Record<string, { template: string }> }>} */
+    const messages = {};
+    for (const m of input.messages || []) {
+        messages[m.messageId] = { variants: m.variants };
+    }
+    const negotiated = negotiateLocale({
+        supportedLocales: supported,
+        defaultLocale,
+        routeLocale: null,
+        userChoice: null,
+        preference: null,
+        hostCandidates: ['zh-TW', 'en'], // must NOT dark-guess
+    });
+    if (negotiated !== defaultLocale) {
+        diagnostics.push({
+            code: DIAG_LOCALE_DIGEST_MISMATCH,
+            severity: 'error',
+            message: `host candidates must not invent LocaleId; got ${negotiated}`,
+        });
+    }
+    const session = createLocaleSession({
+        applicationId: input.applicationId || 'app.locales',
+        deliveryId: input.deliveryId || 'delivery.web',
+        supportedLocales: supported,
+        defaultLocale,
+        fallback,
+        directions,
+        messages,
+        initialLocaleId: defaultLocale,
+        timeZone: input.timeZone || 'Asia/Shanghai',
+        loadedChunks: [defaultLocale],
+    });
+    const fmtCheck = validateFormatterContext(session.formatterContext);
+    diagnostics.push(...fmtCheck.diagnostics);
+    const ssrSnap = session.snapshot();
+    const ssrRender = session.renderAll({
+        'account.greeting': { name: 'Ada' },
+        'account.itemCount': { count: 2 },
+    });
+    const clientSnap = {
+        localeId: ssrSnap.applicationContext.localeId,
+        formatterDigest: ssrSnap.formatterDigest,
+        formatterDataVersion: ssrSnap.formatterContext.formatterDataVersion,
+        texts: Object.fromEntries(Object.entries(ssrRender.bindings).map(([k, v]) => [k, v.text])),
+    };
+    const parity = checkSsrClientParity({
+        ssr: {
+            localeId: ssrSnap.applicationContext.localeId,
+            formatterDigest: ssrSnap.formatterDigest,
+            formatterDataVersion: ssrSnap.formatterContext.formatterDataVersion,
+            texts: clientSnap.texts,
+        },
+        client: clientSnap,
+    });
+    diagnostics.push(...parity.diagnostics);
+    return {
+        schema: LOCALE_RUNTIME_CHECK_SCHEMA,
+        status: diagnostics.some((d) => d.severity === 'error') ? 'failed' : 'ready',
+        negotiatedLocale: negotiated,
+        applicationContext: ssrSnap.applicationContext,
+        formatterContext: ssrSnap.formatterContext,
+        formatterDigest: ssrSnap.formatterDigest,
+        formatterDataVersion: FORMATTER_DATA_VERSION,
+        diagnostics,
+        session,
+    };
+}

package/dist/locale-schema.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Locale I0–I5 schema constants & diagnostic codes.
+ * Design: 规划设计/vmz/28
+ */
+export { FORMATTER_DATA_VERSION, LOCALE_APPLICATION_CONTEXT_SCHEMA, LOCALE_CHECK_SCHEMA, LOCALE_CHUNK_MANIFEST_SCHEMA, LOCALE_CONFORMANCE_SCHEMA, LOCALE_DELIVERY_CHECK_SCHEMA, LOCALE_DELIVERY_RESOLUTION_SCHEMA, LOCALE_DIAG_CACHE_KEY_STEALS_CONTENT as DIAG_LOCALE_CACHE_KEY_STEALS_CONTENT, LOCALE_DIAG_CANONICAL_MISSING as DIAG_LOCALE_CANONICAL_MISSING, LOCALE_DIAG_CATALOG_CONFLICT as DIAG_CATALOG_CONFLICT, LOCALE_DIAG_CATALOG_PARSE as DIAG_CATALOG_PARSE, LOCALE_DIAG_CHUNK_HASH_MISMATCH as DIAG_LOCALE_CHUNK_HASH_MISMATCH, LOCALE_DIAG_CONFORMANCE_DIVERGENCE as DIAG_LOCALE_CONFORMANCE_DIVERGENCE, LOCALE_DIAG_DEFAULT_MISSING as DIAG_DEFAULT_MISSING, LOCALE_DIAG_DELIVERY_FULL_BUNDLE as DIAG_LOCALE_DELIVERY_FULL_BUNDLE, LOCALE_DIAG_DIGEST_MISMATCH as DIAG_LOCALE_DIGEST_MISMATCH, LOCALE_DIAG_DIR_MISSING as DIAG_DIR_MISSING, LOCALE_DIAG_DIR_ORPHAN as DIAG_DIR_ORPHAN, LOCALE_DIAG_EXPLAIN_UNKNOWN as DIAG_LOCALE_EXPLAIN_UNKNOWN, LOCALE_DIAG_FALLBACK_CYCLE as DIAG_FALLBACK_CYCLE, LOCALE_DIAG_FALLBACK_UNKNOWN as DIAG_FALLBACK_UNKNOWN, LOCALE_DIAG_FORMATTER_CONTEXT_INCOMPLETE as DIAG_FORMATTER_CONTEXT_INCOMPLETE, LOCALE_DIAG_FORMATTER_VERSION_MISMATCH as DIAG_FORMATTER_VERSION_MISMATCH, LOCALE_DIAG_HARDCODED_TEXT as DIAG_LOCALE_HARDCODED_TEXT, LOCALE_DIAG_HOST_MESSAGE_DIVERGENCE as DIAG_LOCALE_HOST_MESSAGE_DIVERGENCE, LOCALE_DIAG_HREFLANG_INCOMPLETE as DIAG_LOCALE_HREFLANG_INCOMPLETE, LOCALE_DIAG_ID_COLLISION as DIAG_ID_COLLISION, LOCALE_DIAG_ID_INVALID as DIAG_ID_INVALID, LOCALE_DIAG_LAYOUT_ILLEGAL as DIAG_LAYOUT_ILLEGAL, LOCALE_DIAG_LINK_HARDCODED_PATH as DIAG_LOCALE_LINK_HARDCODED_PATH, LOCALE_DIAG_MACHINE_DEFAULT_FORBIDDEN as DIAG_LOCALE_MACHINE_DEFAULT_FORBIDDEN, LOCALE_DIAG_MANIFEST_MISSING as DIAG_MANIFEST_MISSING, LOCALE_DIAG_MESSAGE_ARRAY_FORBIDDEN as DIAG_MESSAGE_ARRAY_FORBIDDEN, LOCALE_DIAG_MESSAGE_DYNAMIC_ID_UNBOUNDED as DIAG_MESSAGE_DYNAMIC_ID_UNBOUNDED, LOCALE_DIAG_MESSAGE_HTML_FORBIDDEN as DIAG_MESSAGE_HTML_FORBIDDEN, LOCALE_DIAG_MESSAGE_MISSING_DEFAULT as DIAG_MESSAGE_MISSING_DEFAULT, LOCALE_DIAG_MESSAGE_MISSING_VARIANT as DIAG_MESSAGE_MISSING_VARIANT, LOCALE_DIAG_MESSAGE_MIXED_LOCALE as DIAG_MESSAGE_MIXED_LOCALE, LOCALE_DIAG_MESSAGE_PARAMETER_MISMATCH as DIAG_MESSAGE_PARAMETER_MISMATCH, LOCALE_DIAG_MESSAGE_SYNTAX_INVALID as DIAG_MESSAGE_SYNTAX_INVALID, LOCALE_DIAG_MESSAGE_UNUSED as DIAG_MESSAGE_UNUSED, LOCALE_DIAG_META_LOCALE_MISMATCH as DIAG_LOCALE_META_LOCALE_MISMATCH, LOCALE_DIAG_MINI_CROSS_PACKAGE_UNPROVEN as DIAG_LOCALE_MINI_CROSS_PACKAGE_UNPROVEN, LOCALE_DIAG_NATIVE_PACK_APP_MISMATCH as DIAG_LOCALE_NATIVE_PACK_APP_MISMATCH, LOCALE_DIAG_NATIVE_PACK_HAS_JS as DIAG_LOCALE_NATIVE_PACK_HAS_JS, LOCALE_DIAG_NATIVE_PACK_UNSIGNED as DIAG_LOCALE_NATIVE_PACK_UNSIGNED, LOCALE_DIAG_PREFIX_OMIT_WITHOUT_REDIRECT as DIAG_LOCALE_PREFIX_OMIT_WITHOUT_REDIRECT, LOCALE_DIAG_PSEUDO_PRODUCTION_FORBIDDEN as DIAG_LOCALE_PSEUDO_PRODUCTION_FORBIDDEN, LOCALE_DIAG_ROUTE_COLLISION as DIAG_LOCALE_ROUTE_COLLISION, LOCALE_DIAG_SERVER_FORMAT_WITHOUT_CONTEXT as DIAG_LOCALE_SERVER_FORMAT_WITHOUT_CONTEXT, LOCALE_DIAG_SERVER_TRANSLATED_ERROR as DIAG_LOCALE_SERVER_TRANSLATED_ERROR, LOCALE_DIAG_STALE_GENERATION as DIAG_LOCALE_STALE_GENERATION, LOCALE_DIAG_TRANSITION_LOAD_FAILED as DIAG_LOCALE_TRANSITION_LOAD_FAILED, LOCALE_DIAG_TRANSITION_PARTIAL as DIAG_LOCALE_TRANSITION_PARTIAL, LOCALE_DIAG_TRANSITION_UNSUPPORTED as DIAG_LOCALE_TRANSITION_UNSUPPORTED, LOCALE_DIFF_SCHEMA, LOCALE_EXPLAIN_SCHEMA, LOCALE_EXTRACT_SCHEMA, LOCALE_FALLBACK_RESOLUTION_SCHEMA, LOCALE_FORMATTER_CONTEXT_SCHEMA, LOCALE_LINK_RESOLUTION_SCHEMA, LOCALE_MANIFEST_SCHEMA, LOCALE_MESSAGE_CATALOG_SCHEMA as MESSAGE_CATALOG_SCHEMA, LOCALE_MESSAGE_NODE_SCHEMA as MESSAGE_NODE_SCHEMA, LOCALE_MINI_PACKAGE_PROOF_SCHEMA, LOCALE_NATIVE_PACK_SCHEMA, LOCALE_PAGE_META_SCHEMA, LOCALE_PROTOCOL, LOCALE_PSEUDO_SCHEMA, LOCALE_RENAME_SCHEMA, LOCALE_ROUTE_REALIZATION_SCHEMA, LOCALE_ROUTER_CHECK_SCHEMA, LOCALE_RUNTIME_CHECK_SCHEMA, LOCALE_SERVER_ERROR_ENVELOPE_SCHEMA, LOCALE_TRANSITION_SCHEMA, LOCALE_TYPED_MODULE_SCHEMA, LOCALE_VIRTUAL_MODULE_PREFIX, } from '@vmz/protocol';
+/** Reserved first-level names under /locales (not LocaleId dirs). */
+export declare const LOCALE_RESERVED_TOP: Set<string>;
+/** Lowercase ASCII BCP 47-ish with `-` only. */
+export declare const LOCALE_ID_RE: RegExp;

package/dist/locale-schema.js

@@ -0,0 +1,10 @@
+// @ts-nocheck
+/**
+ * Locale I0–I5 schema constants & diagnostic codes.
+ * Design: 规划设计/vmz/28
+ */
+export { FORMATTER_DATA_VERSION, LOCALE_APPLICATION_CONTEXT_SCHEMA, LOCALE_CHECK_SCHEMA, LOCALE_CHUNK_MANIFEST_SCHEMA, LOCALE_CONFORMANCE_SCHEMA, LOCALE_DELIVERY_CHECK_SCHEMA, LOCALE_DELIVERY_RESOLUTION_SCHEMA, LOCALE_DIAG_CACHE_KEY_STEALS_CONTENT as DIAG_LOCALE_CACHE_KEY_STEALS_CONTENT, LOCALE_DIAG_CANONICAL_MISSING as DIAG_LOCALE_CANONICAL_MISSING, LOCALE_DIAG_CATALOG_CONFLICT as DIAG_CATALOG_CONFLICT, LOCALE_DIAG_CATALOG_PARSE as DIAG_CATALOG_PARSE, LOCALE_DIAG_CHUNK_HASH_MISMATCH as DIAG_LOCALE_CHUNK_HASH_MISMATCH, LOCALE_DIAG_CONFORMANCE_DIVERGENCE as DIAG_LOCALE_CONFORMANCE_DIVERGENCE, LOCALE_DIAG_DEFAULT_MISSING as DIAG_DEFAULT_MISSING, LOCALE_DIAG_DELIVERY_FULL_BUNDLE as DIAG_LOCALE_DELIVERY_FULL_BUNDLE, LOCALE_DIAG_DIGEST_MISMATCH as DIAG_LOCALE_DIGEST_MISMATCH, LOCALE_DIAG_DIR_MISSING as DIAG_DIR_MISSING, LOCALE_DIAG_DIR_ORPHAN as DIAG_DIR_ORPHAN, LOCALE_DIAG_EXPLAIN_UNKNOWN as DIAG_LOCALE_EXPLAIN_UNKNOWN, LOCALE_DIAG_FALLBACK_CYCLE as DIAG_FALLBACK_CYCLE, LOCALE_DIAG_FALLBACK_UNKNOWN as DIAG_FALLBACK_UNKNOWN, LOCALE_DIAG_FORMATTER_CONTEXT_INCOMPLETE as DIAG_FORMATTER_CONTEXT_INCOMPLETE, LOCALE_DIAG_FORMATTER_VERSION_MISMATCH as DIAG_FORMATTER_VERSION_MISMATCH, LOCALE_DIAG_HARDCODED_TEXT as DIAG_LOCALE_HARDCODED_TEXT, LOCALE_DIAG_HOST_MESSAGE_DIVERGENCE as DIAG_LOCALE_HOST_MESSAGE_DIVERGENCE, LOCALE_DIAG_HREFLANG_INCOMPLETE as DIAG_LOCALE_HREFLANG_INCOMPLETE, LOCALE_DIAG_ID_COLLISION as DIAG_ID_COLLISION, LOCALE_DIAG_ID_INVALID as DIAG_ID_INVALID, LOCALE_DIAG_LAYOUT_ILLEGAL as DIAG_LAYOUT_ILLEGAL, LOCALE_DIAG_LINK_HARDCODED_PATH as DIAG_LOCALE_LINK_HARDCODED_PATH, LOCALE_DIAG_MACHINE_DEFAULT_FORBIDDEN as DIAG_LOCALE_MACHINE_DEFAULT_FORBIDDEN, LOCALE_DIAG_MANIFEST_MISSING as DIAG_MANIFEST_MISSING, LOCALE_DIAG_MESSAGE_ARRAY_FORBIDDEN as DIAG_MESSAGE_ARRAY_FORBIDDEN, LOCALE_DIAG_MESSAGE_DYNAMIC_ID_UNBOUNDED as DIAG_MESSAGE_DYNAMIC_ID_UNBOUNDED, LOCALE_DIAG_MESSAGE_HTML_FORBIDDEN as DIAG_MESSAGE_HTML_FORBIDDEN, LOCALE_DIAG_MESSAGE_MISSING_DEFAULT as DIAG_MESSAGE_MISSING_DEFAULT, LOCALE_DIAG_MESSAGE_MISSING_VARIANT as DIAG_MESSAGE_MISSING_VARIANT, LOCALE_DIAG_MESSAGE_MIXED_LOCALE as DIAG_MESSAGE_MIXED_LOCALE, LOCALE_DIAG_MESSAGE_PARAMETER_MISMATCH as DIAG_MESSAGE_PARAMETER_MISMATCH, LOCALE_DIAG_MESSAGE_SYNTAX_INVALID as DIAG_MESSAGE_SYNTAX_INVALID, LOCALE_DIAG_MESSAGE_UNUSED as DIAG_MESSAGE_UNUSED, LOCALE_DIAG_META_LOCALE_MISMATCH as DIAG_LOCALE_META_LOCALE_MISMATCH, LOCALE_DIAG_MINI_CROSS_PACKAGE_UNPROVEN as DIAG_LOCALE_MINI_CROSS_PACKAGE_UNPROVEN, LOCALE_DIAG_NATIVE_PACK_APP_MISMATCH as DIAG_LOCALE_NATIVE_PACK_APP_MISMATCH, LOCALE_DIAG_NATIVE_PACK_HAS_JS as DIAG_LOCALE_NATIVE_PACK_HAS_JS, LOCALE_DIAG_NATIVE_PACK_UNSIGNED as DIAG_LOCALE_NATIVE_PACK_UNSIGNED, LOCALE_DIAG_PREFIX_OMIT_WITHOUT_REDIRECT as DIAG_LOCALE_PREFIX_OMIT_WITHOUT_REDIRECT, LOCALE_DIAG_PSEUDO_PRODUCTION_FORBIDDEN as DIAG_LOCALE_PSEUDO_PRODUCTION_FORBIDDEN, LOCALE_DIAG_ROUTE_COLLISION as DIAG_LOCALE_ROUTE_COLLISION, LOCALE_DIAG_SERVER_FORMAT_WITHOUT_CONTEXT as DIAG_LOCALE_SERVER_FORMAT_WITHOUT_CONTEXT, LOCALE_DIAG_SERVER_TRANSLATED_ERROR as DIAG_LOCALE_SERVER_TRANSLATED_ERROR, LOCALE_DIAG_STALE_GENERATION as DIAG_LOCALE_STALE_GENERATION, LOCALE_DIAG_TRANSITION_LOAD_FAILED as DIAG_LOCALE_TRANSITION_LOAD_FAILED, LOCALE_DIAG_TRANSITION_PARTIAL as DIAG_LOCALE_TRANSITION_PARTIAL, LOCALE_DIAG_TRANSITION_UNSUPPORTED as DIAG_LOCALE_TRANSITION_UNSUPPORTED, LOCALE_DIFF_SCHEMA, LOCALE_EXPLAIN_SCHEMA, LOCALE_EXTRACT_SCHEMA, LOCALE_FALLBACK_RESOLUTION_SCHEMA, LOCALE_FORMATTER_CONTEXT_SCHEMA, LOCALE_LINK_RESOLUTION_SCHEMA, LOCALE_MANIFEST_SCHEMA, LOCALE_MESSAGE_CATALOG_SCHEMA as MESSAGE_CATALOG_SCHEMA, LOCALE_MESSAGE_NODE_SCHEMA as MESSAGE_NODE_SCHEMA, LOCALE_MINI_PACKAGE_PROOF_SCHEMA, LOCALE_NATIVE_PACK_SCHEMA, LOCALE_PAGE_META_SCHEMA, LOCALE_PROTOCOL, LOCALE_PSEUDO_SCHEMA, LOCALE_RENAME_SCHEMA, LOCALE_ROUTE_REALIZATION_SCHEMA, LOCALE_ROUTER_CHECK_SCHEMA, LOCALE_RUNTIME_CHECK_SCHEMA, LOCALE_SERVER_ERROR_ENVELOPE_SCHEMA, LOCALE_TRANSITION_SCHEMA, LOCALE_TYPED_MODULE_SCHEMA, LOCALE_VIRTUAL_MODULE_PREFIX, } from '@vmz/protocol';
+/** Reserved first-level names under /locales (not LocaleId dirs). */
+export const LOCALE_RESERVED_TOP = new Set(['locales.json5', 'locales.json', 'package.json']);
+/** Lowercase ASCII BCP 47-ish with `-` only. */
+export const LOCALE_ID_RE = /^[a-z]{2,3}(-[a-z0-9]+)*$/;

package/dist/locale-tooling.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Explain one MessageId: definition, params, variants, fallback, delivery reachability.
+ * @param {{
+ *   messageId: string,
+ *   locale?: string|null,
+ *   deliveryId?: string|null,
+ *   checkReport: any,
+ * }} input
+ */
+export declare function explainLocaleMessage(input: any): {
+    schema: string;
+    status: string;
+    messageId: any;
+    diagnostics: any[];
+    catalogId?: undefined;
+    params?: undefined;
+    variants?: undefined;
+    requestedLocale?: undefined;
+    resolvedLocale?: undefined;
+    fallbackPath?: undefined;
+    formatterDataVersion?: undefined;
+    delivery?: undefined;
+} | {
+    schema: string;
+    status: string;
+    messageId: any;
+    catalogId: any;
+    params: any;
+    variants: {
+        [k: string]: {
+            template: any;
+            path: any;
+            params: any;
+        };
+    };
+    requestedLocale: any;
+    resolvedLocale: any;
+    fallbackPath: any[];
+    formatterDataVersion: string;
+    delivery: {
+        deliveryId: any;
+        reachable: boolean;
+        catalogHash: any;
+        bundledLocales: any[];
+    };
+    diagnostics: any[];
+};
+/**
+ * Diff two locales' catalogs.
+ * @param {{
+ *   baseLocale: string,
+ *   targetLocale: string,
+ *   messages: Array<{ messageId: string, variants: Record<string, { template: string, params?: any[] }> }>,
+ * }} input
+ */
+export declare function diffLocaleCatalogs(input: any): {
+    schema: string;
+    status: string;
+    baseLocale: any;
+    targetLocale: any;
+    missingInTarget: any[];
+    missingInBase: any[];
+    changed: any[];
+    paramMismatches: any[];
+    summary: {
+        missingInTarget: number;
+        missingInBase: number;
+        changed: number;
+        paramMismatches: number;
+    };
+};
+/**
+ * Scan source for likely hardcoded UI text sinks (extract --check).
+ * Does not auto-generate MessageIds.
+ * @param {string} projectRoot
+ * @param {{ check?: boolean }} [opts]
+ */
+export declare function extractHardcodedText(projectRoot: any, opts?: {}): {
+    schema: string;
+    status: string;
+    findings: any[];
+    diagnostics: any[];
+};
+/**
+ * Pseudo-localize a source locale for layout/overflow testing.
+ * Preserves ICU placeholders; marks provenance — never a production fallback.
+ * @param {{
+ *   sourceLocale: string,
+ *   messages: Array<{ messageId: string, variants: Record<string, { template: string }> }>,
+ *   production?: boolean,
+ * }} input
+ */
+export declare function pseudoLocalizeCatalog(input: any): {
+    schema: string;
+    status: string;
+    sourceLocale: any;
+    pseudoLocale: string;
+    provenance: string;
+    catalog: {};
+    diagnostics: any[];
+};
+/**
+ * Cross-host conformance: same MessageId set + catalog hashes + formatter version.
+ * @param {{
+ *   manifest: any,
+ *   messages: any[],
+ *   routeIds?: string[],
+ * }} input
+ */
+export declare function checkLocaleConformance(input: any): {
+    schema: string;
+    status: string;
+    hosts: string[];
+    formatterDataVersion: string;
+    messageIds: any;
+    catalogHashes: {};
+    diagnostics: any[];
+};