@contentrain/types 1.16.0 → 1.18.0

package/dist/index.d.mts

@@ -13,9 +13,10 @@ declare function canonicalStringify(data: unknown, fieldOrder?: readonly string[
 declare const MIGRATION_CONTRACT_VERSION = 1;
 /**
  * How the WordPress site's data was reached, ordered from least to most
- * complete. Measured field coverage rises with each rung (roughly 34% for
- * public REST, 57% with an Application Password, 82% from a WXR export, 100%
- * via the Bridge plugin) — which is why provenance is recorded on every RawIR:
+ * complete. Field coverage rises with each rung — measured in August 2026 at
+ * roughly 34% for public REST, 57% with an Application Password and 82% from a
+ * WXR export; the Bridge plugin reads WordPress from inside and is meant to
+ * reach every field — which is why provenance is recorded on every RawIR:
  * two documents for the same site are only comparable if their rungs are.
  */
 type SourceAccessKind = 'rest_public' | 'rest_auth' | 'wxr' | 'bridge';
@@ -215,13 +216,338 @@ interface RawComment {
   user_id?: number | null;
   meta?: Record<string, unknown>;
 }
-/** A redirect rule (e.g. from the Redirection plugin — visible from the authenticated rung up). */
+/**
+ * How a redirect's `from` is compared with a request path. Only `url` without
+ * `regex` is a plain one-to-one mapping; the others are patterns, and turning
+ * one into a literal `from` produces the wrong redirect.
+ */
+type RawRedirectMatch = 'url' | 'regex' | 'start' | 'contains' | 'end';
+/** A redirect rule the live site serves (e.g. from the Redirection plugin — visible from the authenticated rung up). */
 interface RawRedirect {
   from: string;
   to: string;
   status?: number;
   /** Which plugin/table produced the rule. */
   source?: string;
+  /** Stable id within the export, `<source>:<source-specific id>`. */
+  id?: string;
+  /** How `from` matches; absent means `url`. */
+  match?: RawRedirectMatch;
+  /** `from` is a regular expression in the source's own dialect. */
+  regex?: boolean;
+  /** The source's own module/group serving it, when it has one (e.g. Redirection's "Apache"). */
+  served_by?: string;
+  /** An adjustment the extractor made, stated rather than hidden (e.g. a non-redirect status read as 301). */
+  status_note?: string;
+}
+/**
+ * A rule a source holds that the site does not serve as a plain redirect, with
+ * the reason. Every rule lands in `RawIR.redirects` or here, so the two
+ * together account for the source's whole table.
+ */
+interface RawRedirectExcluded extends Omit<Partial<RawRedirect>, 'match'> {
+  id: string;
+  source: string;
+  /** The source's own match type — may be a condition (`login`, `referrer`, …) rather than a {@link RawRedirectMatch}. */
+  match?: RawRedirectMatch | (string & {});
+  reason: 'disabled' | 'source-inactive' | 'slug-reused' | 'no-slug-address' | `not-a-redirect:${string}` | `conditional-match:${string}`;
+  /** The condition a conditional rule depends on, verbatim. */
+  condition?: unknown;
+}
+declare const SEO_PROVIDERS: readonly ["yoast", "rank_math", "aioseo"];
+type SeoProvider = (typeof SEO_PROVIDERS)[number];
+/** One page's SEO as one provider holds it. */
+interface RawSeoEntry {
+  /** true: the running plugin rendered these values; false: stored values and templates only. */
+  resolved?: boolean;
+  title?: string;
+  description?: string;
+  canonical?: string;
+  robots?: {
+    index?: 'index' | 'noindex';
+    follow?: 'follow' | 'nofollow';
+    advanced?: string[];
+  };
+  /** The directives the page actually carries, after WordPress core and the plugin reconcile them. */
+  robots_served?: string[];
+  open_graph?: {
+    title?: string;
+    description?: string;
+    type?: string;
+    url?: string;
+    image?: string;
+    site_name?: string;
+  };
+  twitter?: {
+    card?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+  };
+  focus_keyword?: string;
+  /** Schema.org types, and the JSON-LD graph when the plugin rendered it. */
+  schema?: {
+    types: string[];
+    graph?: unknown;
+  };
+  /** What the plugin stored for this page (templates such as `%%title%% %%sep%%`), secrets removed. */
+  stored?: Record<string, unknown>;
+}
+/** A provider's site-wide settings. */
+interface RawSeoSettings {
+  separator?: string | null;
+  /** Keyed by context: `post`, `page`, `home`, `author`, `archive`, `tax:<taxonomy>`, `ptarchive-<type>`, … */
+  title_templates: Record<string, string>;
+  description_templates: Record<string, string>;
+  noindex?: Record<string, boolean>;
+  social?: Record<string, unknown>;
+  /** Site verification codes — public meta values. */
+  verification?: Record<string, string>;
+  /** Option name → cleaned value, verbatim otherwise. */
+  raw: Record<string, unknown>;
+}
+/**
+ * The site's SEO layer: which plugin serves the head, its settings, and each
+ * page's values. `status: 'none'` is an answer — no SEO plugin, and WordPress
+ * core renders only the title — not a missing export.
+ */
+interface RawSeo {
+  /** Producer's format identifier, e.g. `contentrain-bridge-seo@1`. */
+  format?: string;
+  status: 'present' | 'none';
+  /** Whose output the live site serves. */
+  serving: SeoProvider | 'wordpress-core';
+  providers: Record<SeoProvider, {
+    status: 'active' | 'inactive-with-data' | 'absent';
+    version?: string;
+  }>;
+  settings: Partial<Record<SeoProvider, RawSeoSettings>>;
+  /** `post:<id>` or `term:<taxonomy>:<id>` → one block per provider that has data for it. */
+  entries: Record<string, Partial<Record<SeoProvider, RawSeoEntry>>>;
+  /** Values deliberately not exported (e.g. a sensitive key), by address. */
+  excluded?: {
+    source: string;
+    reason: string;
+  }[];
+}
+/** A page WordPress routes to itself (front page, posts page). */
+interface RawRoutedPage {
+  id: number;
+  slug: string;
+  /** Site-root-relative address. */
+  path: string;
+}
+/**
+ * The site's URL rules — what `RawPost.link` holds as facts, stated as the
+ * structure that produced them. Permastructs are site-root-relative with
+ * `front` already applied where `with_front` asks for it.
+ */
+interface RawRouting {
+  /** Producer's format identifier, e.g. `contentrain-bridge-routing@1`. */
+  format?: string;
+  /** The site's home URL. */
+  home?: string;
+  permalink_structure: string;
+  /** Plain `?p=` permalinks — no structure at all. */
+  plain: boolean;
+  trailing_slash: boolean;
+  front: string;
+  category_base: string;
+  tag_base: string;
+  pagination_base: string;
+  author_base: string;
+  search_base: string;
+  feed_base?: string;
+  comments_pagination_base?: string;
+  author_structure?: string | null;
+  date_structure?: string | null;
+  page_structure?: string | null;
+  /** `posts` or `page`. */
+  show_on_front: string;
+  page_on_front?: RawRoutedPage | null;
+  page_for_posts?: RawRoutedPage | null;
+  posts_per_page: number;
+  post_types: {
+    name: string;
+    hierarchical: boolean;
+    rewrite: {
+      slug?: string;
+      with_front?: boolean;
+      feeds?: boolean;
+      pages?: boolean;
+    } | false;
+    permastruct: string | null;
+    has_archive: boolean;
+    archive_path: string | null;
+    query_var: string | false;
+  }[];
+  taxonomies: {
+    name: string;
+    object_types: string[];
+    hierarchical: boolean;
+    rewrite: {
+      slug?: string;
+      with_front?: boolean;
+      hierarchical?: boolean;
+    } | false;
+    permastruct: string | null;
+  }[];
+}
+/** Where a candidate was found. */
+declare const TEXT_CANDIDATE_KINDS: readonly ["php-gettext", "php-html", "php-echo", "html", "js", "widget", "menu", "option", "customizer", "render"];
+type RawTextCandidateKind = (typeof TEXT_CANDIDATE_KINDS)[number];
+/** Why a candidate is not transferred. `RawTextCandidate.reason` joins one or more with `,`. */
+declare const TEXT_EXCLUDE_REASONS: readonly ["empty", "too-long", "secret", "code", "url", "number", "no-letters", "placeholder-only", "dynamic", "not-text", "content", "rendered-from-source"];
+type RawTextExcludeReason = (typeof TEXT_EXCLUDE_REASONS)[number];
+/** Where a transferred candidate lands in the store. */
+type RawTextTarget = 'dictionary:ui-strings' | `theme-settings.${string}` | 'site.title' | 'site.description' | 'content:wp-menu-items';
+/** One place a candidate's text was found. */
+interface RawTextOccurrence {
+  kind: RawTextCandidateKind;
+  /** A file path relative to `wp-content`, `render:<state>`, `nav_menu_item#<id>`, … */
+  source: string;
+  /** 1-based line in a file; `0` for a source without lines (render, menu, option). */
+  line: number;
+}
+/**
+ * One piece of interface text in one place. Candidates merge only when text,
+ * locale and context are all equal: "Read more" in an `a` and in a `button`
+ * are two candidates, and so are `_x('Post', 'noun')` and `_x('Post', 'verb')`.
+ */
+interface RawTextCandidate {
+  /** `sha256(text \0 locale \0 context)`, first 20 hex characters. */
+  id: string;
+  /** The text; `[redacted]` when `reason` includes `secret`. */
+  value: string;
+  locale: string;
+  /**
+   * Where the text sits: an HTML tag (`a`, `input@placeholder`),
+   * `gettext[:<ctx>][:plural]`, `js`, `widget:<tag>` / `widget:title`, `menu`,
+   * `option:<name>`, `customizer:<mod>`, or for rendered text
+   * `<landmark>><tag>` (`footer>p`, `nav>nav@aria-label`).
+   */
+  context: string;
+  kind: RawTextCandidateKind;
+  /** The first occurrence's `source` and `line`. */
+  source: string;
+  line: number;
+  /** Every place the text was found, in the producer's listing order. */
+  occurrences: RawTextOccurrence[];
+  outcome: 'transfer' | 'exclude';
+  /** Set exactly when `outcome` is `transfer`. */
+  target?: RawTextTarget;
+  /** Set exactly when `outcome` is `exclude`: one or more `RawTextExcludeReason`s joined with `,`. */
+  reason?: string;
+  /**
+   * With `rendered-from-source`: ids of the source candidates this page text
+   * came from. Page text found in source is excluded here and transferred
+   * there, so the same words never land twice and contexts are not merged.
+   */
+  related?: string[];
+  /**
+   * The store key: `<group>.<context>.<words>-<sha256(text \0 context)[0:6]>`,
+   * or `theme-settings.<mod>` for a Customizer value. A function of text and
+   * context only — moving a string to another file changes no key. A
+   * collision fails the export rather than merging two texts.
+   */
+  key: string;
+  decision: 'review' | 'include' | 'exclude';
+}
+/**
+ * Every piece of interface text a site shows, each with one outcome. Totals
+ * close: `by_outcome.transfer + by_outcome.exclude = candidates`,
+ * `by_outcome.error = errors.length`, and `occurrences` counts every
+ * occurrence the scanners found — listed ones plus those past the per-file
+ * listing cap, which are counted by reason instead.
+ */
+interface RawHardcodedText {
+  /** Producer's format identifier, e.g. `contentrain-bridge-hardcoded-text@1`. */
+  format: string;
+  candidates: RawTextCandidate[];
+  /**
+   * Sources that could not be read — an outcome, not a silent gap. Reasons:
+   * `source-over-2MiB`, `source-unreadable`, `render-fetch-failed: <code>`,
+   * `render-http-<status>`, `render-no-body`.
+   */
+  errors: {
+    source: string;
+    reason: string;
+  }[];
+  totals: {
+    occurrences: number;
+    occurrences_listed: number; /** Occurrences past the listing cap: excluded and counted, not listed. */
+    unlisted_excluded: number;
+    unlisted_by_reason: Record<string, number>;
+    candidates: number;
+    by_outcome: {
+      transfer: number;
+      exclude: number;
+      error: number;
+    };
+    sources: {
+      files: number;
+      settings: number;
+      render_states: number;
+    };
+  };
+}
+declare const INTEGRATION_CATEGORIES: readonly ["analytics", "crm", "newsletter", "ads", "comments", "captcha", "cdn", "other"];
+type IntegrationCategory = (typeof INTEGRATION_CATEGORIES)[number];
+declare const INTEGRATION_EVIDENCE_KINDS: readonly ["plugin", "option-key", "script-domain", "form-config", "embed-domain"];
+type IntegrationEvidenceKind = (typeof INTEGRATION_EVIDENCE_KINDS)[number];
+/** One outside service the site uses, and why we believe it does. */
+interface RawIntegration {
+  /** Catalog id: `mailchimp`, `hubspot`, `google-tag-manager`, `jetpack-stats`, `embed-youtube`, … */
+  service: string;
+  /** Display name. */
+  name: string;
+  category: IntegrationCategory;
+  /**
+   * Never a value. `detail` names a plugin and its version, a setting by name
+   * (`mc4wp (api_key)`), a script host and where it was seen
+   * (`static.hotjar.com @ render:home`), a form's wiring, or an embed host.
+   */
+  evidence: {
+    kind: IntegrationEvidenceKind;
+    detail: string;
+  }[];
+  /** An account must be connected again on the new site; `false` for an embed, which has no account. */
+  reconnect_required: boolean;
+  /** A credential is configured on WordPress. Only this boolean is exported, never the value. */
+  secret_present: boolean;
+  /** What to do, in words for the person receiving the site. */
+  notes: string;
+}
+/**
+ * The document a bridge writes (`bridge/integrations.json`). `RawIR.integrations`
+ * carries its `services`. An empty `services` with `scanned` beside it is an
+ * answer — the site uses no outside service we recognise — not a missing scan.
+ */
+interface RawIntegrationScan {
+  /** Producer's format identifier, e.g. `contentrain-bridge-integrations@1`. */
+  format: string;
+  /** How much was looked at: option and post counts, active plugins, script sources, and whether the home page was rendered. */
+  scanned: {
+    options: number;
+    plugins: number;
+    posts: number;
+    rendered_home: boolean;
+    script_sources: number;
+  };
+  services: RawIntegration[];
+  totals: {
+    services: number;
+    reconnect_required: number;
+  };
+}
+/**
+ * The intake / handoff issue for services that must be connected again. Raised
+ * once, listing every `RawIntegration` with `reconnect_required: true`; not
+ * raised when there are none.
+ */
+interface IntegrationReconnectRequiredIssue {
+  code: 'integration_reconnect_required';
+  services: Pick<RawIntegration, 'service' | 'name' | 'category' | 'secret_present'>[];
 }
 /**
  * Translation grouping for multilingual sites. The REST rungs read it from
@@ -250,6 +576,14 @@ interface RawIR {
   menus?: RawMenu[];
   comments?: RawComment[];
   redirects?: RawRedirect[];
+  /** Rules the sources hold that the site does not serve as plain redirects. */
+  redirects_excluded?: RawRedirectExcluded[];
+  seo?: RawSeo;
+  routing?: RawRouting;
+  /** Interface text outside the content tables, each piece with one outcome. */
+  hardcoded_text?: RawHardcodedText;
+  /** Outside services the site is connected to (`RawIntegrationScan.services`). */
+  integrations?: RawIntegration[];
   language_pairs?: RawLanguagePair[];
   /** Site options (bridge rung), verbatim. */
   options?: Record<string, unknown>;
@@ -760,6 +1094,22 @@ interface HandoffOffer {
   /** e.g. "keeping comments on WordPress means the WordPress server stays live". */
   warning?: string;
 }
+/**
+ * What a standalone page's body is, as far as the migration can carry it.
+ *
+ * - `html` — markup written in the editor. It travels as content and stays
+ *   editable.
+ * - `builder_html` — markup a page builder rendered (the builder's own data
+ *   is not HTML). It travels as it was rendered: the page looks right, but its
+ *   layout is no longer edited in the builder that made it.
+ * - `none` — no body; the theme renders the page from other data. Nothing to
+ *   carry as content.
+ *
+ * Counted because they promise different things to the person receiving the
+ * site, and a single "pages migrated" number hides which promise was made.
+ */
+declare const PAGE_BODY_KINDS: readonly ["html", "builder_html", "none"];
+type PageBodyKind = (typeof PAGE_BODY_KINDS)[number];
 interface MigrationHandoff {
   version: number;
   site_url: string;
@@ -776,6 +1126,11 @@ interface MigrationHandoff {
     models: number;
     entries: number;
     locales?: string[];
+    /**
+     * Standalone pages by body kind — see `PageBodyKind`. Every kind is present
+     * when the field is, so a zero is a count, not an omission.
+     */
+    body_kinds?: Record<PageBodyKind, number>;
   };
   capabilities: HandoffCapability[];
   /** Present whenever the source had comments — see `HandoffComments`. */
@@ -1224,11 +1579,51 @@ interface SourceDeltaEntry {
   /** Origin content fingerprint at cursor time and now. */
   fingerprint_before?: string;
   fingerprint_after?: string;
-  /** For `moved`: the slugs, in that order. Redirects are generated from these. */
+  /** For `moved`: the slugs, in that order. */
   slug_before?: string;
   slug_after?: string;
+  /**
+   * For `moved`: the site-root-relative addresses, in that order. A slug
+   * cannot say that a page changed parent, a term base changed or a dated
+   * permalink moved; the path can, and redirects are generated from it.
+   */
+  path_before?: string;
+  path_after?: string;
+  /**
+   * For `deleted`: `trashed` is still at the origin and can come back;
+   * `purged` is gone from it. A draft or private record is `updated`, never
+   * `deleted` — unpublishing is the planner's decision.
+   */
+  deleted_kind?: 'trashed' | 'purged';
   /** True when the repository also changed this record since the cursor. */
   conflict?: boolean;
+  /**
+   * The repository-side write behind `conflict`: the entry's meta when it was
+   * last written by something other than the importer (Studio, an agent, a
+   * person). `updated_at` is absent when the store never recorded it — an
+   * unknown time is still a conflict.
+   */
+  repo_edit?: {
+    updated_by: string;
+    updated_at?: string;
+    source: string;
+  };
+  /**
+   * Why the planner could not place this record in the store:
+   * `not-in-source-map` (a post-type record the source map does not list),
+   * `no-model-for-type` (no store model holds this origin type),
+   * `entry-not-found` (the model exists, the entry does not).
+   */
+  unmapped?: 'not-in-source-map' | 'no-model-for-type' | 'entry-not-found';
+  /**
+   * For `updated` and `moved`: the fields whose stored value differs from the
+   * incoming export's, by field name (`body` for a document's body). Computed
+   * against the repository as it is now, so a repository-side edit shows here
+   * too — which is what `conflict` is for.
+   */
+  fields_changed?: string[];
+  /** For `moved`: the entry id at the new address, when the store derives ids from slugs and the id changes. */
+  entry_id_after?: string;
   /** Why this entry is here, for the person reading the plan. */
   detail?: string;
 }
@@ -1253,6 +1648,12 @@ interface SourceDeltaPlan {
    * "nothing was deleted".
    */
   deletions_detectable: boolean;
+  /**
+   * Origin types whose deletions could not be determined even though the plan
+   * as a whole could — a type that left the inventory's scope (its plugin was
+   * deactivated) is not a deletion of every record in it.
+   */
+  deletions_undetectable_types?: string[];
   /** Redirects implied by the `moved` entries. */
   redirects?: {
     from: string;
@@ -1286,6 +1687,67 @@ declare function planHashPayload(plan: ExecutionPlan): string;
  * value, so a collision is an approval bypass, not a cache miss.
  */
 declare function computePlanHash(plan: ExecutionPlan): Promise<string>;
+/** One origin record as the inventory saw it. */
+interface SourceInventoryRecord {
+  /** Origin object type ("post", "page", "attachment", or a taxonomy name for a term). */
+  wp_type: string;
+  /** Origin id — unique only together with `wp_type`: post 5 and category 5 are different records. */
+  wp_id: number;
+  /** Origin status (`publish`, `draft`, `trash`, …); a term has none. */
+  status?: string;
+  /**
+   * Password-protected at the origin. The record is inventoried like any other
+   * — so removing the password is an `updated`, not a `created` — but has no
+   * public address.
+   */
+  protected?: boolean;
+  slug?: string;
+  /** Site-root-relative public address. A change here is a `moved`. */
+  path?: string;
+  /** Origin id of the parent record, when it has one. */
+  parent?: number;
+  /** ISO 8601 UTC, from the origin — a hint only: a meta-only edit does not change it. */
+  modified_at?: string;
+  /**
+   * Hash of the record as mapped, volatile fields excluded. `updated` is
+   * decided on this, never on `modified_at`.
+   */
+  fingerprint: string;
+  /** Slugs the origin remembers for this record (WordPress `_wp_old_slug`). Corroborates a move; never the authority. */
+  old_slugs?: string[];
+  /** Locale of the record, when the origin is multilingual. */
+  locale?: string;
+}
+/**
+ * Every record in scope at one moment — what a `bridge_inventory` cursor's
+ * `inventory_hash` identifies.
+ *
+ * Deletions and moves are proven by comparing two inventories, not by
+ * reading a feed; a `modified_after` query only narrows which bodies to fetch
+ * again. A type in the earlier inventory's `scope` but not in this one's left
+ * the scope — it was not deleted.
+ */
+interface SourceInventory {
+  /** Inventory format identifier, e.g. `contentrain-bridge-inventory@2`. */
+  format: string;
+  /** ISO 8601 UTC time the inventory was taken. */
+  taken_at: string;
+  /** What was enumerated. */
+  scope: {
+    post_types: string[];
+    taxonomies?: string[];
+  };
+  records: SourceInventoryRecord[];
+  /**
+   * The value a cursor's `inventory_hash` carries: lowercase hex SHA-256 of the
+   * records sorted by `wp_type` (byte order) then `wp_id` (numeric), each
+   * serialized as the JSON array `[wp_type, wp_id, fingerprint, path ?? null,
+   * status ?? null]` — no spaces, slashes and non-ASCII unescaped (what
+   * `JSON.stringify` prints) — joined by `\n`, no trailing newline. Other fields
+   * do not enter it; a change they make shows through `fingerprint`.
+   */
+  inventory_hash: string;
+}
 //#endregion
 //#region src/approval.d.ts
 /**
@@ -1881,6 +2343,23 @@ interface ModelDefinition {
   kind: ModelKind;
   domain: string;
   i18n: boolean;
+  /**
+   * The project locales this model's content actually covers — a subset of
+   * `config.locales.supported`.
+   *
+   * Absent means every project locale, which is the behaviour every model had
+   * before this field existed: parity is checked against the whole supported
+   * list. Present, it narrows that check to the locales named here, so a
+   * partially-translated site can declare the truth instead of failing.
+   *
+   * A locale not in `config.locales.supported` is a validation error — see
+   * {@link validateModelLocales}. Meaningless on a non-i18n model, which has
+   * only the default locale.
+   *
+   * It narrows validation; it never grants a locale. Writing content in a
+   * locale outside this list is still governed by `config.locales.supported`.
+   */
+  locales?: string[];
   /**
    * Name of the field whose value is shown as an entry's title — in a Studio row,
    * a picker, a relation reference. Declared, never guessed: a consumer that infers
@@ -2130,7 +2609,7 @@ declare const CANONICAL_JSON: {
  * the `keyof` assertion in index.test.ts catches a `ModelDefinition` key missing
  * from this array. Between them, drift fails `tsc`, which runs on every commit.
  */
-declare const MODEL_FIELD_ORDER: readonly ["id", "name", "kind", "domain", "i18n", "title_field", "description", "content_path", "locale_strategy", "fields", "form", "comments"];
+declare const MODEL_FIELD_ORDER: readonly ["id", "name", "kind", "domain", "i18n", "locales", "title_field", "description", "content_path", "locale_strategy", "fields", "form", "comments"];
 interface ScaffoldTemplate {
   id: string;
   models: ModelDefinition[];
@@ -2316,6 +2795,51 @@ declare function validateSlug(slug: string): string | null;
 declare function validateEntryId(id: string): string | null;
 /** Validate a locale code against pattern and config — returns error message or null if valid */
 declare function validateLocale(locale: string, config: ContentrainConfig): string | null;
+/**
+ * The locales one model's content is checked against, and where that list came
+ * from — `'model'` when the model narrowed it with `locales`, `'project'` when
+ * it is the project-wide list (or, for a non-i18n model, the default locale).
+ *
+ * The provenance travels with the list because every message derived from it
+ * has to say which list it evaluated: "missing tr" means something different
+ * when tr is one of four project locales than when the model declares it.
+ */
+interface ModelLocaleScope {
+  locales: string[];
+  source: 'model' | 'project';
+}
+/**
+ * The locales a model's content is expected to cover.
+ *
+ * A non-i18n model stores content locale-agnostically, so its scope is the
+ * default locale alone — unchanged, and `locales` never applies to it. An i18n
+ * model narrows to `model.locales` when it declares one, otherwise it covers
+ * every supported locale, which is what every model did before the field
+ * existed.
+ *
+ * Locales are returned in `config.locales.supported` order, not the order the
+ * model happened to list them: a message that names the list should read the
+ * same for two models that declare the same locales differently. Anything the
+ * model names that the project does not support is dropped here and reported
+ * by {@link validateModelLocales} — resolution never invents coverage.
+ */
+declare function resolveModelLocales(model: Pick<ModelDefinition, 'i18n' | 'locales'>, config: ContentrainConfig): ModelLocaleScope;
+/** Name a locale scope the way a validation message should quote it. */
+declare function describeModelLocaleScope(scope: ModelLocaleScope): string;
+/**
+ * Check a model's `locales` declaration against the project config.
+ *
+ * Absent is valid and means every supported locale, so this returns nothing for
+ * the models that predate the field. What it rejects is a declaration that
+ * cannot be honoured: a locale the project does not support (the coverage would
+ * be unreachable), an empty list (a model that covers nothing is a deleted
+ * model, not a narrowed one), a duplicate, or a non-string entry.
+ *
+ * Declaring `locales` on a non-i18n model is a warning, not an error: the field
+ * has no effect there, but the model is still readable and its content still
+ * validates, so failing the project over it would be out of proportion.
+ */
+declare function validateModelLocales(model: Pick<ModelDefinition, 'i18n' | 'locales'>, config: ContentrainConfig): ValidationError[];
 /**
  * Does a value assigned to an API-key setting look like a credential rather
  * than prose about one?
@@ -2462,5 +2986,5 @@ declare function parseMarkdownFrontmatter(content: string): {
 /** Serialize data + body into markdown frontmatter format */
 declare function serializeMarkdownFrontmatter(data: Record<string, unknown>, body: string): string;
 //#endregion
-export { APPROVAL_GATES, APPROVAL_MODES, ActorRef, type ApplyPlanInput, ApprovalDecision, ApprovalEvaluation, ApprovalGate, ApprovalGrant, ApprovalMode, ApprovalPolicyFile, ApprovalRequirement, ApprovalRule, ApprovalStatus, AssetEntry, AutomationDefinition, AutomationSchedule, type BaseAdvance, type Branch, CANONICAL_JSON, CAPABILITY_KEYS, CHROME_BODY_SLOT, CHROME_COMPONENT_CLOSE, CHROME_COMPONENT_OPEN, CHROME_IF_CLOSE, CHROME_IF_OPEN, CHROME_REPEAT_CLOSE, CHROME_REPEAT_OPEN, COMMENTS_EXPORT_FORMAT, COMPONENT_TYPES, CONTENTRAIN_BRANCH, CONTENTRAIN_DIR, CapabilityDetection, CapabilityDisposition, CapabilityKey, CapabilityManifest, Checkpoint, ChromeChunk, CollectionContentFile, CollectionContentOutput, CollectionEntry, CollectionMeta, CollectionRuntimeFormat, CommentsExport, type Commit, type CommitAuthor, ComponentDef, ComponentPlacement, ComponentSource, ComponentType, ComponentVariantDef, type ConflictCode, type ConflictItem, type ConflictResolution, ContentSource, ContentStatus, ContentrainConfig, ContentrainError, ContextJson, ContextSource, CostComparison, CostEstimate, CssStrategy, DEFAULT_APPROVAL_POLICY, DICTIONARY_TITLE_FIELD, DeploymentTarget, DesignTokens, DictionaryContentFile, DictionaryMeta, DocumentContentOutput, DocumentEntry, DocumentMeta, DuplicateGroup, ENTRY_ID_PATTERN, EXECUTION_CONTRACT_VERSION, EntryMeta, EntrySourceMap, EntrySourceRef, ExcerptSource, ExecutionCost, ExecutionEstimate, ExecutionPlan, ExecutionReceipt, ExecutionScope, ExecutionStep, FamilyVariant, FieldDef, FieldType, FileCategory, type FileChange, type FileDiff, FileFramework, GrantRejection, GraphNode, HandoffCapability, HandoffComments, HandoffOffer, LEGACY_CSS_LAYER, LIST_ITEMS_SLOT, LOCALE_PATTERN, LOCAL_CAPABILITIES, LayoutFamily, LocaleStrategy, MIGRATION_CONTRACT_VERSION, MODEL_EXTENSION_KEYS, MODEL_FIELD_ORDER, type MediaAsset, type MediaIngestInput, type MediaListOptions, type MediaListResult, type MediaProvider, type MediaUpdateInput, type MergeResult, MigrationHandoff, MisfirePolicy, ModelDefinition, ModelKind, ModelSummary, NormalizePlan, NormalizePlanExtraction, NormalizePlanModel, NormalizePlanPatch, OfferProvider, PATH_PATTERNS, PaginationKind, Platform, PolymorphicRelationRef, ProjectGraph, ProjectIR, ProjectRef, type ProviderCapabilities, QueryBinding, RAW_MARK_SUFFIX, RESERVED_PATHS, RISK_CLASSES, RUN_STATUSES, RawAcfValue, RawAttachment, RawAuthor, RawComment, RawIR, RawLanguagePair, RawMenu, RawMenuItem, RawMenuTarget, RawPost, RawProvenance, RawRedirect, RawSite, RawTerm, RawTermRef, RejectedGrant, type RemotePush, type RepoProvider, type RepoReader, type RepoWriter, RiskClass, RollbackPlan, RootAttrs, RouteKind, RouteModel, RouteParamDef, RouteVariantRule, RunStatus, RuntimeBinding, SCHEDULE_KINDS, SECRET_PATTERNS, SLUG_PATTERN, SOURCE_ACCESS_LADDER, SOURCE_DELTA_OPS, ScaffoldTemplate, ScanCandidate, ScanCandidatesResult, ScanSummaryResult, ScheduleKind, SingletonContentFile, SingletonMeta, SlotBinding, SlotKind, SourceAccessKind, SourceCursor, SourceDeltaEntry, SourceDeltaOp, SourceDeltaPlan, StackType, StringContext, SyncResult, TERMINAL_RUN_STATUSES, TITLE_FIELD_TYPES, ValidationError, ValidationResult, VerificationCheck, ViewportStrategy, Vocabulary, WorkflowMode, type WriteReadiness, approversFor, canonicalStringify, componentSlot, computePlanHash, conflictId, detectSecrets, effectiveRisk, evaluateApproval, generateEntryId, highestRisk, isMediaType, isReservedPath, isTerminalRunStatus, isTitleFieldType, looksLikeCredential, orderedFieldNames, parseFrontmatterScalar, parseFrontmatterScalarString, parseMarkdownFrontmatter, planHashPayload, requiredApprovals, resolveFieldLabel, riskRank, serializeMarkdownFrontmatter, sortKeys, splitFrontmatterList, stableHash, validateAccept, validateEntryId, validateFieldValue, validateLocale, validateSemanticType, validateSlug };
+export { APPROVAL_GATES, APPROVAL_MODES, ActorRef, type ApplyPlanInput, ApprovalDecision, ApprovalEvaluation, ApprovalGate, ApprovalGrant, ApprovalMode, ApprovalPolicyFile, ApprovalRequirement, ApprovalRule, ApprovalStatus, AssetEntry, AutomationDefinition, AutomationSchedule, type BaseAdvance, type Branch, CANONICAL_JSON, CAPABILITY_KEYS, CHROME_BODY_SLOT, CHROME_COMPONENT_CLOSE, CHROME_COMPONENT_OPEN, CHROME_IF_CLOSE, CHROME_IF_OPEN, CHROME_REPEAT_CLOSE, CHROME_REPEAT_OPEN, COMMENTS_EXPORT_FORMAT, COMPONENT_TYPES, CONTENTRAIN_BRANCH, CONTENTRAIN_DIR, CapabilityDetection, CapabilityDisposition, CapabilityKey, CapabilityManifest, Checkpoint, ChromeChunk, CollectionContentFile, CollectionContentOutput, CollectionEntry, CollectionMeta, CollectionRuntimeFormat, CommentsExport, type Commit, type CommitAuthor, ComponentDef, ComponentPlacement, ComponentSource, ComponentType, ComponentVariantDef, type ConflictCode, type ConflictItem, type ConflictResolution, ContentSource, ContentStatus, ContentrainConfig, ContentrainError, ContextJson, ContextSource, CostComparison, CostEstimate, CssStrategy, DEFAULT_APPROVAL_POLICY, DICTIONARY_TITLE_FIELD, DeploymentTarget, DesignTokens, DictionaryContentFile, DictionaryMeta, DocumentContentOutput, DocumentEntry, DocumentMeta, DuplicateGroup, ENTRY_ID_PATTERN, EXECUTION_CONTRACT_VERSION, EntryMeta, EntrySourceMap, EntrySourceRef, ExcerptSource, ExecutionCost, ExecutionEstimate, ExecutionPlan, ExecutionReceipt, ExecutionScope, ExecutionStep, FamilyVariant, FieldDef, FieldType, FileCategory, type FileChange, type FileDiff, FileFramework, GrantRejection, GraphNode, HandoffCapability, HandoffComments, HandoffOffer, INTEGRATION_CATEGORIES, INTEGRATION_EVIDENCE_KINDS, IntegrationCategory, IntegrationEvidenceKind, IntegrationReconnectRequiredIssue, LEGACY_CSS_LAYER, LIST_ITEMS_SLOT, LOCALE_PATTERN, LOCAL_CAPABILITIES, LayoutFamily, LocaleStrategy, MIGRATION_CONTRACT_VERSION, MODEL_EXTENSION_KEYS, MODEL_FIELD_ORDER, type MediaAsset, type MediaIngestInput, type MediaListOptions, type MediaListResult, type MediaProvider, type MediaUpdateInput, type MergeResult, MigrationHandoff, MisfirePolicy, ModelDefinition, ModelKind, ModelLocaleScope, ModelSummary, NormalizePlan, NormalizePlanExtraction, NormalizePlanModel, NormalizePlanPatch, OfferProvider, PAGE_BODY_KINDS, PATH_PATTERNS, PageBodyKind, PaginationKind, Platform, PolymorphicRelationRef, ProjectGraph, ProjectIR, ProjectRef, type ProviderCapabilities, QueryBinding, RAW_MARK_SUFFIX, RESERVED_PATHS, RISK_CLASSES, RUN_STATUSES, RawAcfValue, RawAttachment, RawAuthor, RawComment, RawHardcodedText, RawIR, RawIntegration, RawIntegrationScan, RawLanguagePair, RawMenu, RawMenuItem, RawMenuTarget, RawPost, RawProvenance, RawRedirect, RawRedirectExcluded, RawRedirectMatch, RawRoutedPage, RawRouting, RawSeo, RawSeoEntry, RawSeoSettings, RawSite, RawTerm, RawTermRef, RawTextCandidate, RawTextCandidateKind, RawTextExcludeReason, RawTextOccurrence, RawTextTarget, RejectedGrant, type RemotePush, type RepoProvider, type RepoReader, type RepoWriter, RiskClass, RollbackPlan, RootAttrs, RouteKind, RouteModel, RouteParamDef, RouteVariantRule, RunStatus, RuntimeBinding, SCHEDULE_KINDS, SECRET_PATTERNS, SEO_PROVIDERS, SLUG_PATTERN, SOURCE_ACCESS_LADDER, SOURCE_DELTA_OPS, ScaffoldTemplate, ScanCandidate, ScanCandidatesResult, ScanSummaryResult, ScheduleKind, SeoProvider, SingletonContentFile, SingletonMeta, SlotBinding, SlotKind, SourceAccessKind, SourceCursor, SourceDeltaEntry, SourceDeltaOp, SourceDeltaPlan, SourceInventory, SourceInventoryRecord, StackType, StringContext, SyncResult, TERMINAL_RUN_STATUSES, TEXT_CANDIDATE_KINDS, TEXT_EXCLUDE_REASONS, TITLE_FIELD_TYPES, ValidationError, ValidationResult, VerificationCheck, ViewportStrategy, Vocabulary, WorkflowMode, type WriteReadiness, approversFor, canonicalStringify, componentSlot, computePlanHash, conflictId, describeModelLocaleScope, detectSecrets, effectiveRisk, evaluateApproval, generateEntryId, highestRisk, isMediaType, isReservedPath, isTerminalRunStatus, isTitleFieldType, looksLikeCredential, orderedFieldNames, parseFrontmatterScalar, parseFrontmatterScalarString, parseMarkdownFrontmatter, planHashPayload, requiredApprovals, resolveFieldLabel, resolveModelLocales, riskRank, serializeMarkdownFrontmatter, sortKeys, splitFrontmatterList, stableHash, validateAccept, validateEntryId, validateFieldValue, validateLocale, validateModelLocales, validateSemanticType, validateSlug };
 //# sourceMappingURL=index.d.mts.map