@contentrain/types 1.17.0 → 1.18.0

package/README.md

@@ -55,6 +55,7 @@ Core interfaces:
 
 - `FieldDef`
 - `ModelDefinition`
+- `ModelLocaleScope`
 - `ModelSummary`
 - `ContentrainConfig`
 - `Vocabulary`
@@ -127,6 +128,9 @@ Validate functions (pure, dependency-free):
 - `validateSlug(slug)` — kebab-case slug validation
 - `validateEntryId(id)` — entry ID format validation
 - `validateLocale(locale, config)` — locale format + config support check
+- `resolveModelLocales(model, config)` — the locales a model's content is expected to cover: `model.locales` when it declares one, otherwise `config.locales.supported` (the default locale alone when `i18n: false`)
+- `describeModelLocaleScope(scope)` — name a resolved scope the way a validation message should quote it
+- `validateModelLocales(model, config)` — check a `locales` declaration is a subset of `config.locales.supported`
 - `detectSecrets(value)` — detect potential secrets in field values (provider-shaped patterns, plus an `api_key = …` assignment whose tail passes `looksLikeCredential`)
 - `validateFieldValue(value, fieldDef)` — full field schema validation (type, required, min/max, pattern, select)
 
@@ -182,6 +186,9 @@ const model: ModelDefinition = {
   kind: 'collection',
   domain: 'blog',
   i18n: true,
+  // Optional. Absent means every locale in config.locales.supported; a subset
+  // narrows validation for a partially-translated model.
+  locales: ['en', 'tr'],
   fields,
 }
 
@@ -250,6 +257,8 @@ Studio (Nuxt 4, web) cannot import `@contentrain/mcp` directly because MCP depen
 | `validateSlug(slug)` | Form validation for document slugs |
 | `validateEntryId(id)` | Validate collection entry IDs |
 | `validateLocale(locale, config)` | Locale picker validation |
+| `resolveModelLocales(model, config)` | Which locales to show, or require, for one model |
+| `validateModelLocales(model, config)` | Validate a model's locale-coverage subset in a model editor |
 | `detectSecrets(value)` | Content editor secret detection warnings |
 | `validateFieldValue(value, fieldDef)` | Full field-level validation in content forms |
 | `canonicalStringify(data, fieldOrder?)` | Preview canonical JSON output |
@@ -328,7 +337,7 @@ Shared shapes for the WordPress → static-site migration pipeline. They exist h
 
 | Contract | Role |
 |---|---|
-| `RawIR` | Source-faithful extraction of a WordPress site (posts, terms, menus, comments, media, redirects) with provenance: which access rung produced it (`rest_public` → `rest_auth` → `wxr` → `bridge`). Unresolved references are kept and marked, never dropped. |
+| `RawIR` | Source-faithful extraction of a WordPress site (posts, terms, menus, comments, media, redirects, and from the bridge rung SEO and routing) with provenance: which access rung produced it (`rest_public` → `rest_auth` → `wxr` → `bridge`). Unresolved references are kept and marked, never dropped. |
 | `CapabilityManifest` | Evidence-based inventory of what the site uses (SEO, forms, comments, i18n, ACF, …) — the input for migration planning and the "what happens to X" conversation. `access.achieved` is the highest source-access rung actually reached, or `null` when none was: a site behind an access wall still gets a manifest, and a producer that writes a rung it did not reach makes the coverage figures unreadable. |
 | `ProjectIR` | The reproducible model of the site: route model, layout families, component variants, query bindings, design tokens. Not "this page's HTML" — the design system that generates unseen pages correctly. |
 | `MigrationHandoff` | What the migration hands the user: repository, per-capability dispositions, and offers for runtime capabilities (with cost comparison) — offering is this document's job; fulfilling is the receiving product's. `runtime` (`RuntimeBinding`) records where the generated site's runtime components were bound once an offer was fulfilled. `content_summary.body_kinds` counts standalone pages by `PageBodyKind` — `html` (editor markup, still editable), `builder_html` (rendered by a page builder, carried as rendered), `none` (the theme renders it) — because each promises something different to the person receiving the site. |
@@ -336,6 +345,16 @@ Shared shapes for the WordPress → static-site migration pipeline. They exist h
 
 All are plain JSON (snake_case keys), stamped with `MIGRATION_CONTRACT_VERSION`.
 
+`RawIR` also carries five optional parts from the bridge rung:
+
+- **`seo`** (`RawSeo`) holds which plugin serves the head (`serving`: `yoast` / `rank_math` / `aioseo` / `wordpress-core`), each provider's status and settings, and each page's values keyed by `post:<id>` or `term:<taxonomy>:<id>`. `status: 'none'` is an answer, not a missing export: no SEO plugin, and WordPress core renders only the title. `resolved: true` marks values the running plugin rendered; `false` marks stored values and templates only. `robots_served` is what the page actually carries after WordPress core and the plugin reconcile it.
+- **`routing`** (`RawRouting`) states the URL rules that `RawPost.link` holds as facts: permalink structure, bases, the front and posts pages, and each post type's and taxonomy's permastruct, with `with_front` applied.
+- **`redirects_excluded`** (`RawRedirectExcluded`) lists every rule a source holds that the site does not serve as a plain redirect, with the reason (`disabled`, `source-inactive`, `conditional-match:*`, `not-a-redirect:*`, …). Served plus excluded accounts for the whole table.
+- **`hardcoded_text`** (`RawHardcodedText`) accounts for the interface text outside the content tables — theme templates, scripts, widgets, menus, options, Customizer mods and rendered pages. Each `RawTextCandidate` has one outcome: `transfer` to a `target` (`dictionary:ui-strings`, `theme-settings.<mod>`, `site.title`, `site.description`, `content:wp-menu-items`) or `exclude` with a `reason` (`TEXT_EXCLUDE_REASONS`); a source that could not be read is listed in `errors`. Candidates merge only when text, locale and context are equal, and `key` depends on text and context only. Page text that also appears in source is `rendered-from-source` with `related` pointing at the source candidate, so the same words never land twice. `totals` closes: transfer + exclude = candidates, and error = `errors.length`.
+- **`integrations`** (`RawIntegration[]`) lists the outside services the site is connected to (`INTEGRATION_CATEGORIES`: analytics, crm, newsletter, ads, comments, captcha, cdn, other), each with its evidence. Evidence names a plugin, a setting, a script host, a form's wiring or an embed host, never a value. `reconnect_required` is `false` only for an embed, which has no account. `secret_present` says a credential is set on WordPress; the credential itself is never exported. `IntegrationReconnectRequiredIssue` (`code: 'integration_reconnect_required'`) is the one intake/handoff issue that lists every service to connect again.
+
+`RawRedirect` gains `id`, `match` and `regex`. Only `match: 'url'` without `regex` is a one-to-one mapping. A consumer that writes a regex or prefix rule as a literal `from` produces the wrong redirect.
+
 Chrome markers the emitter honours: `CHROME_BODY_SLOT` (where page content goes), `CHROME_REPEAT_OPEN`/`CHROME_IF_OPEN` (per-item and conditional regions), `LIST_ITEMS_SLOT` (where a list section's items go) and `componentSlot(id)` (`<!--@@component:ID@@-->`, where a `ComponentDef` — a `comments` thread, a `form` — is mounted).
 
 `ModelDefinition` can carry runtime-owned `form` and `comments` configuration.
@@ -365,6 +384,7 @@ approval guarding it would be theatre.
 | `DeploymentTarget` | Where a build is published. Carries a `secret_ref`, never a secret — this document is written to git. |
 | `AutomationDefinition` | Reserved shape for `.contentrain/automations.json`. Nothing reads it yet; it exists so the first writer does not invent a fourth vocabulary for schedules. |
 | `SourceDeltaPlan` | The WordPress→repo delta — *not* `contentrain_reconcile`, which merges two git branches and knows nothing about WordPress. Carries explicit deletion tombstones, because `modified_after` is a filter on changed records and never reports a deletion, plus slug moves (which generate redirects) and semantic conflicts. `deletions_detectable: false` must not be read as "nothing was deleted". |
+| `SourceInventory` / `SourceInventoryRecord` | Every origin record in scope at one moment — what a `bridge_inventory` cursor's hash identifies. Deletions and moves are proven by comparing two inventories (records keyed by `wp_type` + `wp_id`, updates decided on `fingerprint`); `modified_after` only narrows what to fetch again. `SourceDeltaEntry` also carries `path_before`/`path_after` for moves a slug cannot express, and `deleted_kind` (`trashed` / `purged`). |
 
 ### The evaluator
 

package/dist/index.d.mts

@@ -216,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
@@ -251,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>;
@@ -1246,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;
 }
@@ -1275,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;
@@ -1308,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
 /**
@@ -1903,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
@@ -2152,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[];
@@ -2338,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?
@@ -2484,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, 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, 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