@contentrain/types 1.1.0 → 1.3.0

package/dist/index.d.mts

@@ -1,3 +1,495 @@
+//#region src/migration.d.ts
+/**
+ * Version stamped into every migration document (`version` field on each root).
+ * The four contracts evolve together with this package; a reader that sees a
+ * higher version than it knows should refuse rather than guess.
+ */
+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:
+ * two documents for the same site are only comparable if their rungs are.
+ */
+type SourceAccessKind = 'rest_public' | 'rest_auth' | 'wxr' | 'bridge';
+/** The ladder in ascending completeness order. */
+declare const SOURCE_ACCESS_LADDER: readonly ["rest_public", "rest_auth", "wxr", "bridge"];
+interface RawProvenance {
+  kind: SourceAccessKind;
+  /** ISO 8601 UTC time the extraction ran. */
+  fetched_at?: string;
+  /** Name/version of the producing tool (e.g. "wordpress-bridge/1.0"). */
+  tool?: string;
+}
+interface RawSite {
+  url: string;
+  title?: string;
+  description?: string;
+  /** WXR distinguishes the WP install URL from the public site URL. */
+  base_site_url?: string;
+  base_blog_url?: string;
+  /** Site language as reported (e.g. "en-US"); multilingual detail lives in `language_pairs`. */
+  language?: string | null;
+  /** Generator string (WordPress version) when the source exposed it. */
+  generator?: string | null;
+  /** WXR export timestamp, when the source was a WXR file. */
+  export_date?: string | null;
+  wxr_version?: string | null;
+}
+interface RawAuthor {
+  id: number | null;
+  login: string;
+  email?: string | null;
+  display_name: string;
+  first_name?: string | null;
+  last_name?: string | null;
+}
+interface RawTerm {
+  id: number | null;
+  taxonomy: string;
+  slug: string;
+  name: string;
+  /** Parent term slug within the same taxonomy, when hierarchical. */
+  parent?: string | null;
+  /** Whether `parent` names a term present in this document. */
+  parent_resolved?: boolean | null;
+  description?: string;
+}
+/** A post's reference to a term — kept even when the term itself is absent. */
+interface RawTermRef {
+  taxonomy: string;
+  slug: string;
+  name: string;
+  /** Whether the referenced term exists in this document's `terms`. */
+  resolved: boolean;
+}
+/** An ACF field value paired with its field-definition key (`field_…`). */
+interface RawAcfValue {
+  value: unknown;
+  field_key: string;
+}
+interface RawPost {
+  id: number;
+  /** WordPress post type — "post", "page", or a custom post type slug. */
+  type: string;
+  /** WordPress status verbatim ("publish", "draft", "future", "pending", …). */
+  status: string;
+  slug: string;
+  title: string;
+  /** Public permalink, when known. Permalink *structure* is a site setting; the link is the fact. */
+  link?: string | null;
+  guid?: string | null;
+  /** Author login; resolve against `RawIR.authors`. */
+  author: string | null;
+  /** ISO 8601 UTC, null when the source carried no usable date. */
+  date: string | null;
+  modified: string | null;
+  /** Rendered/exported HTML body, untransformed. */
+  content: string;
+  excerpt: string;
+  parent?: number | null;
+  menu_order?: number;
+  sticky?: boolean;
+  password?: string | null;
+  comment_status?: string | null;
+  ping_status?: string | null;
+  terms: RawTermRef[];
+  /**
+   * Post meta, PHP-serialized values already decoded where possible.
+   * Core WP keys (underscore-prefixed) are included: which keys matter is a
+   * downstream decision.
+   */
+  meta: Record<string, unknown>;
+  /** Meta keys whose values were PHP-serialized in the source (decoded above). */
+  serialized_keys?: string[];
+  /** ACF fields recovered by pairing `foo` with `_foo = "field_…"`. */
+  acf?: Record<string, RawAcfValue>;
+}
+interface RawAttachment {
+  id: number;
+  title: string;
+  slug: string;
+  /** Original file URL. Downloading/re-hosting is a consumer concern. */
+  url: string | null;
+  alt?: string;
+  caption?: string;
+  description?: string;
+  /** Relative upload path (`_wp_attached_file`), when present. */
+  file?: string | null;
+  /** `_wp_attachment_metadata` verbatim (sizes, EXIF, …). */
+  image_meta?: unknown;
+  mime?: string | null;
+  parent?: number | null;
+  parent_resolved?: boolean | null;
+  author?: string | null;
+  date?: string | null;
+  status?: string;
+  meta?: Record<string, unknown>;
+}
+/** Where a menu item points. `resolved` says whether the target exists in this document. */
+type RawMenuTarget = {
+  kind: 'url';
+  url: string;
+  resolved: true;
+} | {
+  kind: 'post';
+  post_type: string;
+  id: number | null;
+  slug: string | null;
+  resolved: boolean;
+} | {
+  kind: 'term';
+  taxonomy: string;
+  id: number | null;
+  slug: string | null;
+  resolved: boolean;
+} | {
+  kind: 'archive';
+  post_type: string;
+  resolved: true;
+} | {
+  kind: 'unknown';
+  resolved: false;
+};
+interface RawMenuItem {
+  id: number;
+  title: string;
+  order?: number;
+  /** Parent menu-item id for nested menus. */
+  parent?: number | null;
+  parent_unresolved?: boolean;
+  url?: string | null;
+  target: RawMenuTarget;
+  /** `target` attribute for the rendered link (e.g. "_blank"). */
+  target_attr?: string | null;
+  classes?: string[];
+  description?: string;
+  status?: string;
+}
+interface RawMenu {
+  id: number | null;
+  slug: string;
+  name: string;
+  items: RawMenuItem[];
+}
+interface RawComment {
+  id: number;
+  /** Post id this comment belongs to. */
+  post: number;
+  post_type?: string;
+  parent?: number | null;
+  parent_resolved?: boolean | null;
+  author: string;
+  email?: string | null;
+  url?: string | null;
+  date: string | null;
+  content: string;
+  /** WordPress approval flag verbatim ("1", "0", "spam", …). */
+  approved?: string;
+  type?: string;
+  user_id?: number | null;
+  meta?: Record<string, unknown>;
+}
+/** A redirect rule (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;
+}
+/** Translation grouping for multilingual sites (Polylang/WPML — bridge rung). */
+interface RawLanguagePair {
+  post: number;
+  /** locale → post id of the translation. */
+  translations: Record<string, number>;
+}
+/**
+ * The complete raw extraction of one WordPress site at one access rung.
+ * This is the boundary document between extraction (Bridge/importers) and
+ * everything downstream — content conversion, capability analysis, migration.
+ */
+interface RawIR {
+  version: number;
+  provenance: RawProvenance;
+  site: RawSite;
+  authors: RawAuthor[];
+  terms: RawTerm[];
+  posts: RawPost[];
+  attachments: RawAttachment[];
+  menus?: RawMenu[];
+  comments?: RawComment[];
+  redirects?: RawRedirect[];
+  language_pairs?: RawLanguagePair[];
+  /** Site options (bridge rung), verbatim. */
+  options?: Record<string, unknown>;
+}
+declare const CAPABILITY_KEYS: readonly ["seo", "forms", "comments", "search", "newsletter", "analytics", "consent", "share", "video", "ads", "builder", "blocks", "i18n", "cache", "security", "acf", "ecommerce", "jetpack", "redirects", "membership", "accessibility", "media", "scheduling"];
+type CapabilityKey = (typeof CAPABILITY_KEYS)[number];
+interface CapabilityDetection {
+  present: boolean;
+  /** Identified plugin/provider, when known (e.g. "yoast", "contact-form-7"). */
+  plugin?: string | null;
+  /** How it was detected: "rest", "dom", "slug", "headers", "meta", … */
+  evidence?: string[];
+  detail?: string;
+}
+interface CapabilityManifest {
+  version: number;
+  site_url: string;
+  access: {
+    html_status?: number | null;
+    rest_status?: number | null; /** Highest source-access rung actually achieved for this site. */
+    achieved: SourceAccessKind;
+  };
+  generator?: string | null;
+  theme?: string | null;
+  plugins?: string[];
+  rest_namespaces?: string[];
+  custom_post_types?: Array<{
+    slug: string; /** Whether the CPT is exposed in public REST (`rest: false` CPTs need a higher rung). */
+    rest_visible: boolean;
+    count?: number | null;
+  }>;
+  /** Comments get first-class treatment: they are a launch-critical capability. */
+  comments: {
+    active: boolean;
+    form_status?: 'open' | 'closed' | 'mixed' | null;
+    rest_total?: number | null;
+    plugin?: string | null;
+  };
+  capabilities: Partial<Record<CapabilityKey, CapabilityDetection>>;
+  /** Dynamic front-end behaviors observed in the DOM ("carousel", "modal", "search-overlay", …). */
+  behaviors?: string[];
+  languages?: string[];
+}
+/**
+ * How the legacy CSS for a family was packaged.
+ * - `purge_set`: rules kept if used by any page in the family's page set —
+ *   small file, safe against per-page rule loss (single-page purging is not).
+ * - `localcss`: the site's stylesheets localized wholesale — larger, zero risk.
+ */
+type CssStrategy = 'purge_set' | 'localcss';
+/**
+ * Cascade layer name the emitter quarantines legacy CSS under, so a modern
+ * utility layer (e.g. Tailwind) can coexist with pixel-faithful migrated pages.
+ */
+declare const LEGACY_CSS_LAYER = "legacy";
+/** Design tokens extracted from the source site, e.g. for a Tailwind `@theme` block. */
+interface DesignTokens {
+  colors?: Record<string, string>;
+  font_families?: Record<string, string>;
+  font_sizes?: Record<string, string>;
+  spacing?: Record<string, string>;
+  breakpoints?: Record<string, string>;
+}
+type RouteKind = 'front' | 'single' | 'page' | 'archive' | 'term' | 'author' | 'date' | 'search' | 'not_found' | 'custom';
+interface RouteParamDef {
+  name: string;
+  source: 'post_slug' | 'term_slug' | 'author_slug' | 'page_number' | 'custom';
+}
+/** Selects a family/component variant when a route parameter matches. */
+interface RouteVariantRule {
+  param: string;
+  in: string[];
+  variant: string;
+}
+/**
+ * One route pattern → one layout family. Pagination is a parameter of a route
+ * (`/news/page/2` is `/news` with `page_number = 2`), never a separate family —
+ * across a 30-site corpus, page 2 never produced a new layout.
+ */
+interface RouteModel {
+  id: string;
+  /** URL pattern with `:param` placeholders, e.g. "/category/:term", "/news/page/:page". */
+  pattern: string;
+  kind: RouteKind;
+  /** LayoutFamily id. */
+  family: string;
+  params?: RouteParamDef[];
+  /** QueryBinding id feeding this route's list, when it renders one. */
+  query?: string;
+  variant_rules?: RouteVariantRule[];
+}
+type SlotKind = 'body' | 'title' | 'date' | 'excerpt' | 'author_name' | 'author_link' | 'featured_image' | 'term_list' | 'self_link' | 'custom';
+/** Where a content field lands in a family's markup. */
+interface SlotBinding {
+  kind: SlotKind;
+  /** CSS selector of the slot's container, when one could be determined. */
+  selector?: string;
+  /** Content-model field backing a `custom` slot. */
+  field?: string;
+  /** Date rendering format for `date` slots, as observed on the source site. */
+  date_format?: string;
+}
+/** A rendered, asset-rewritten chunk of site chrome the emitter injects verbatim. */
+interface ChromeChunk {
+  id: string;
+  position: 'head' | 'before_body' | 'after_body';
+  html: string;
+}
+interface ComponentPlacement {
+  /** ComponentDef id. */
+  component: string;
+  variant?: string;
+  selector?: string;
+}
+interface FamilyVariant {
+  key: string;
+  description?: string;
+}
+interface LayoutFamily {
+  id: string;
+  name?: string;
+  kind?: RouteKind;
+  chrome?: ChromeChunk[];
+  slots?: SlotBinding[];
+  components?: ComponentPlacement[];
+  css: {
+    strategy: CssStrategy; /** Emitted stylesheet paths, relative to the generated project. */
+    files?: string[];
+  };
+  /** Observed column counts per viewport class (e.g. desktop 4 → mobile 1). */
+  columns?: Partial<Record<'desktop' | 'mobile', number>>;
+  variants?: FamilyVariant[];
+  /** Verification trail: which pages formed the family, held-out fidelity score. */
+  evidence?: {
+    pages?: string[];
+    holdout_score?: number;
+  };
+}
+/**
+ * Component semantic vocabulary. `source` records where its content can come
+ * from: `rest` (derivable from content data — author box, term list),
+ * `runtime` (needs a live service — comments form, search), `chrome` (carried
+ * as rendered markup — nav, ads).
+ */
+declare const COMPONENT_TYPES: readonly ["nav", "related", "comments", "ads", "chrome", "taxonomy", "author", "share", "breadcrumb", "meta", "pagination", "card", "custom"];
+type ComponentType = (typeof COMPONENT_TYPES)[number];
+type ComponentSource = 'rest' | 'runtime' | 'chrome';
+interface ComponentVariantDef {
+  key: string;
+  conditions?: RouteVariantRule[];
+  description?: string;
+}
+interface ComponentDef {
+  id: string;
+  type: ComponentType;
+  source: ComponentSource;
+  name?: string;
+  selector?: string;
+  /** e.g. a card component with `news`, `compact`, `featured` variants. */
+  variants?: ComponentVariantDef[];
+}
+type ExcerptSource = 'excerpt' | 'content_first_paragraph' | 'none';
+type PaginationKind = 'numbered' | 'infinite' | 'none';
+/**
+ * The query behind a rendered list: which content, filtered how, in what
+ * order, how many. Inferred by matching rendered items against candidate
+ * queries — order matters, so the sequence is part of the contract.
+ */
+interface QueryBinding {
+  id: string;
+  /** Content source: "posts", "pages", a CPT slug, or a content-model id. */
+  source: string;
+  taxonomy?: {
+    taxonomy: string; /** Fixed term slug, or the route param carrying it. */
+    term?: string;
+    term_param?: string;
+  };
+  author?: {
+    slug?: string;
+    param?: string;
+  };
+  order: {
+    by: 'date' | 'title' | 'menu_order' | 'custom';
+    direction: 'asc' | 'desc';
+  };
+  per_page: number | null;
+  pagination: PaginationKind;
+  excerpt_source?: ExcerptSource;
+  /** WordPress image size name the list renders (e.g. "medium_large"). */
+  image_size?: string;
+}
+/**
+ * - `responsive`: one build, CSS handles viewports.
+ * - `split`: desktop and mobile variants are produced separately and served
+ *   by device — for sites whose mobile DOM differs beyond CSS.
+ */
+type ViewportStrategy = 'responsive' | 'split';
+interface ProjectIR {
+  version: number;
+  site: {
+    url: string;
+    title?: string;
+    locales?: string[];
+  };
+  routes: RouteModel[];
+  families: LayoutFamily[];
+  components?: ComponentDef[];
+  queries?: QueryBinding[];
+  tokens?: DesignTokens;
+  /** Default CSS packaging for families that don't override it. */
+  css_default: CssStrategy;
+  viewport_strategy?: ViewportStrategy;
+  /** Content-model ids this project's queries and slots refer to. */
+  content_models?: string[];
+}
+type CapabilityDisposition = 'migrated_static' | 'archived' | 'needs_runtime' | 'external_adapter' | 'kept_on_wordpress' | 'dropped';
+interface HandoffCapability {
+  key: CapabilityKey;
+  disposition: CapabilityDisposition;
+  detail?: string;
+  /** e.g. comments: { migrated: 412, spam_skipped: 60 } */
+  counts?: Record<string, number>;
+}
+type OfferProvider = 'studio_managed' | 'adapter' | 'keep_wordpress';
+interface CostEstimate {
+  currency: string;
+  monthly: number;
+  assumptions?: string[];
+}
+/**
+ * The comparison shown when a runtime capability is offered: what running the
+ * old server costs (maintenance, security, hosting) against the managed
+ * option — so declining is an informed choice, not a default.
+ */
+interface CostComparison {
+  self_host?: CostEstimate;
+  managed?: CostEstimate;
+}
+interface HandoffOffer {
+  capability: CapabilityKey;
+  provider: OfferProvider;
+  /** Adapter identifier when `provider` is `adapter`. */
+  adapter?: string;
+  cost_comparison?: CostComparison;
+  /** e.g. "keeping comments on WordPress means the WordPress server stays live". */
+  warning?: string;
+}
+interface MigrationHandoff {
+  version: number;
+  site_url: string;
+  /** ISO 8601 UTC. */
+  generated_at: string;
+  repository?: {
+    provider: 'github' | 'gitlab';
+    owner: string;
+    name: string;
+    default_branch: string;
+  };
+  preview_url?: string;
+  content_summary?: {
+    models: number;
+    entries: number;
+    locales?: string[];
+  };
+  capabilities: HandoffCapability[];
+  offers?: HandoffOffer[];
+  notes?: string[];
+}
+//#endregion
 //#region src/provider.d.ts
 /**
  * A single file change within a plan.
@@ -38,6 +530,13 @@ interface ProviderCapabilities {
   pullRequestFallback: boolean;
   /** Provider can execute AST scanners against source files. Implies local disk access. */
   astScan: boolean;
+  /**
+   * Provider can write a two-parent merge commit (see
+   * `RepoProvider.createMergeCommit`). Absent = false. Optional so that
+   * existing external `implements` code keeps compiling: a required member
+   * here would be a breaking change for every custom provider.
+   */
+  mergeCommit?: boolean;
 }
 /** Capability set for the LocalProvider (simple-git + worktree). */
 declare const LOCAL_CAPABILITIES: ProviderCapabilities;
@@ -95,6 +594,15 @@ interface Commit {
   sync?: SyncResult;
   /** Non-fatal problem encountered while completing the write. */
   warning?: string;
+  /**
+   * Whether the base branch advanced to the contentrain tip after an
+   * auto-merge. Only providers that own the base advance (a local worktree)
+   * report it. `blocked_diverged` is a partial success: the content is on
+   * the contentrain branch; only the fast-forward is pending.
+   */
+  base_advance?: BaseAdvance;
+  /** Outcome of pushing the contentrain branch, when the provider pushes. */
+  remote_push?: RemotePush;
 }
 /**
  * Input to `applyPlan`. Represents a single atomic commit: all changes land
@@ -175,6 +683,86 @@ interface MergeResult {
     warning?: string;
   };
 }
+/**
+ * What happened to the base branch after content landed on the
+ * content-tracking branch.
+ *
+ * `advanced` — the base branch fast-forwarded to the contentrain tip.
+ * `blocked_diverged` — the base branch holds commits that are not in
+ * contentrain, so fast-forwarding was impossible. The content itself is
+ * safe on the contentrain branch; only the advance is pending until the
+ * branches are reconciled.
+ *
+ * These two values are shared vocabulary across the ecosystem — Studio
+ * reports the same enum for its main-advance state. A pull request is an
+ * attachment (`pullRequestUrl`), never a third state: "PR opened" is
+ * `blocked_diverged` with a non-null URL.
+ */
+type BaseAdvance = 'advanced' | 'blocked_diverged';
+/**
+ * Outcome of pushing the content-tracking branch to the configured remote.
+ *
+ * `pushed` — the remote accepted the push (possibly after one
+ * fetch-merge-retry). `rejected` — the push failed even after the retry;
+ * local and remote have diverged and need reconciling. `no-remote` — the
+ * repository has no configured remote, so nothing was attempted.
+ */
+type RemotePush = 'pushed' | 'rejected' | 'no-remote';
+/**
+ * Machine-readable conflict kinds produced by the content-aware three-way
+ * reconcile planner. CLOSED SET: consumers (Studio) key their localized
+ * editor questions on these values, so a free string would drift. Adding a
+ * value here is a minor version bump and MUST carry a changelog entry;
+ * renaming or removing one is breaking.
+ */
+type ConflictCode = 'field_value_conflict' | 'dictionary_value_conflict' | 'vocabulary_value_conflict' | 'model_key_conflict' | 'meta_status_conflict' | 'document_body_conflict' | 'frontmatter_value_conflict' | 'delete_edit_conflict' | 'file_conflict';
+/**
+ * One surviving conflict from a three-way reconcile: base (merge-base),
+ * ours (content branch), theirs (base branch) disagree in a way the policy
+ * table cannot resolve mechanically. Everything mechanical has already been
+ * merged; only these items need a decision from an editor or agent.
+ *
+ * `id` is derived from the position AND the three values (see
+ * `conflictId`), so a resolution made against a stale dry-run no longer
+ * matches once any side changes — compare-and-set for free.
+ */
+interface ConflictItem {
+  id: string;
+  /** Content-root-relative path of the file the conflict lives in. */
+  path: string;
+  model?: string;
+  kind: 'collection' | 'singleton' | 'document' | 'dictionary' | 'vocabulary' | 'model' | 'meta' | 'file';
+  /** Entry ID, dictionary key, vocabulary term, or model schema key. */
+  key?: string;
+  /** Field inside the entry / frontmatter key, when the conflict is field-level. */
+  field?: string;
+  locale?: string;
+  /** The three values in question — for display; omitted for `kind: 'file'`. */
+  base?: unknown;
+  ours?: unknown;
+  theirs?: unknown;
+  code: ConflictCode;
+  /** Ready-to-display English sentence naming the conflict. */
+  message: string;
+  /**
+   * Policy-table suggestion, never auto-applied. Present only where the
+   * approved policy names a preferred side (model schema keys → `theirs`).
+   */
+  suggested?: 'ours' | 'theirs';
+}
+/**
+ * A decision for one conflict, keyed by `ConflictItem.id`. `choose` picks a
+ * side (absence of the item on that side means deletion); `value` supplies
+ * a hand-authored replacement. A resolution whose `id` no longer matches a
+ * live conflict is dropped and the conflict re-reported with a fresh id.
+ */
+type ConflictResolution = {
+  id: string;
+  choose: 'ours' | 'theirs';
+} | {
+  id: string;
+  value: unknown;
+};
 /**
  * One media asset as the provider's media stack reports it. `path` is the
  * repo-relative storage path content fields reference (`media/...`); `url`
@@ -310,6 +898,40 @@ interface RepoProvider extends RepoReader, RepoWriter {
   }): Promise<MergeResult>;
   isMerged(branch: string, into?: string): Promise<boolean>;
   getDefaultBranch(): Promise<string>;
+  /**
+   * The merge-base commit of two refs — the `base` input of a three-way
+   * reconcile.
+   *
+   * Reconciling a diverged content branch needs the last common ancestor,
+   * and every backend can name it (git `merge-base`, GitHub's compare API,
+   * GitLab's merge_base endpoint) — but not every existing implementation
+   * does yet, and demanding it would break external `implements` code.
+   *
+   * Optional: a provider that omits it cannot drive a reconcile; the caller
+   * falls back to a pull-request flow. Returns `null` when the refs share
+   * no history.
+   */
+  getMergeBase?(refA: string, refB: string): Promise<string | null>;
+  /**
+   * Write a set of resolved changes as a TWO-PARENT merge commit on
+   * `branch`, joining `ours` and `theirs` so that git history records the
+   * reconcile — after it, `theirs` is an ancestor of `branch` and a plain
+   * fast-forward advance works again. `changes` are applied on top of the
+   * `ours` tree; for content-owned paths the planner's output is
+   * authoritative, never a textual auto-merge.
+   *
+   * Optional, mirrored by `capabilities.mergeCommit`: a backend whose
+   * commits API cannot express two parents (GitLab) omits it and the
+   * caller falls back to a merge-request flow.
+   */
+  createMergeCommit?(input: {
+    /** Branch whose tip becomes the merge commit (the content branch). */branch: string; /** First parent — the current tip of `branch`. */
+    ours: string; /** Second parent — the ref being reconciled in. */
+    theirs: string;
+    changes: FileChange[];
+    message: string;
+    author: CommitAuthor;
+  }): Promise<Commit>;
 }
 //#endregion
 //#region src/index.d.ts
@@ -825,6 +1447,32 @@ declare function sortKeys(obj: unknown, fieldOrder?: readonly string[]): unknown
 declare function canonicalStringify(data: unknown, fieldOrder?: readonly string[]): string;
 /** Generate a 12-character hex entry ID */
 declare function generateEntryId(): string;
+/**
+ * FNV-1a 64-bit over the input's UTF-8 code points, returned as 16 hex
+ * chars. Deliberately dependency-free (no `node:crypto` — this package has
+ * zero runtime imports and runs anywhere). Not cryptographic; the use case
+ * is change detection, not tamper resistance.
+ */
+declare function stableHash(input: string): string;
+/**
+ * Identity of a reconcile conflict: position AND values. Hashing the three
+ * values into the id makes every resolution a compare-and-set — if any side
+ * changes between the dry-run that produced the conflict and the apply that
+ * carries the decision, the id no longer matches, the stale resolution is
+ * dropped, and the conflict is re-reported with a fresh id. Values are
+ * normalized through `sortKeys` first so semantically equal objects hash
+ * equal regardless of key order; the positional array keeps absent and
+ * null distinguishable per slot.
+ */
+declare function conflictId(conflict: {
+  path: string;
+  key?: string;
+  field?: string;
+  locale?: string;
+  base?: unknown;
+  ours?: unknown;
+  theirs?: unknown;
+}): string;
 /** Parse markdown frontmatter — extracts YAML frontmatter and body from a markdown string */
 declare function parseMarkdownFrontmatter(content: string): {
   frontmatter: Record<string, unknown>;
@@ -833,5 +1481,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 { type ApplyPlanInput, AssetEntry, type Branch, CANONICAL_JSON, CONTENTRAIN_BRANCH, CONTENTRAIN_DIR, CollectionContentFile, CollectionContentOutput, CollectionEntry, CollectionMeta, CollectionRuntimeFormat, type Commit, type CommitAuthor, ContentSource, ContentStatus, ContentrainConfig, ContentrainError, ContextJson, ContextSource, DICTIONARY_TITLE_FIELD, DictionaryContentFile, DictionaryMeta, DocumentContentOutput, DocumentEntry, DocumentMeta, DuplicateGroup, ENTRY_ID_PATTERN, EntryMeta, FieldDef, FieldType, FileCategory, type FileChange, type FileDiff, FileFramework, GraphNode, LOCALE_PATTERN, LOCAL_CAPABILITIES, LocaleStrategy, MODEL_FIELD_ORDER, type MediaAsset, type MediaIngestInput, type MediaListOptions, type MediaListResult, type MediaProvider, type MediaUpdateInput, type MergeResult, ModelDefinition, ModelKind, ModelSummary, NormalizePlan, NormalizePlanExtraction, NormalizePlanModel, NormalizePlanPatch, PATH_PATTERNS, Platform, PolymorphicRelationRef, ProjectGraph, type ProviderCapabilities, type RepoProvider, type RepoReader, type RepoWriter, SECRET_PATTERNS, SLUG_PATTERN, ScaffoldTemplate, ScanCandidate, ScanCandidatesResult, ScanSummaryResult, SingletonContentFile, SingletonMeta, StackType, StringContext, SyncResult, TITLE_FIELD_TYPES, ValidationError, ValidationResult, Vocabulary, WorkflowMode, type WriteReadiness, canonicalStringify, detectSecrets, generateEntryId, isMediaType, isTitleFieldType, orderedFieldNames, parseMarkdownFrontmatter, resolveFieldLabel, serializeMarkdownFrontmatter, sortKeys, validateAccept, validateEntryId, validateFieldValue, validateLocale, validateSemanticType, validateSlug };
+export { type ApplyPlanInput, AssetEntry, type BaseAdvance, type Branch, CANONICAL_JSON, CAPABILITY_KEYS, COMPONENT_TYPES, CONTENTRAIN_BRANCH, CONTENTRAIN_DIR, CapabilityDetection, CapabilityDisposition, CapabilityKey, CapabilityManifest, ChromeChunk, CollectionContentFile, CollectionContentOutput, CollectionEntry, CollectionMeta, CollectionRuntimeFormat, type Commit, type CommitAuthor, ComponentDef, ComponentPlacement, ComponentSource, ComponentType, ComponentVariantDef, type ConflictCode, type ConflictItem, type ConflictResolution, ContentSource, ContentStatus, ContentrainConfig, ContentrainError, ContextJson, ContextSource, CostComparison, CostEstimate, CssStrategy, DICTIONARY_TITLE_FIELD, DesignTokens, DictionaryContentFile, DictionaryMeta, DocumentContentOutput, DocumentEntry, DocumentMeta, DuplicateGroup, ENTRY_ID_PATTERN, EntryMeta, ExcerptSource, FamilyVariant, FieldDef, FieldType, FileCategory, type FileChange, type FileDiff, FileFramework, GraphNode, HandoffCapability, HandoffOffer, LEGACY_CSS_LAYER, LOCALE_PATTERN, LOCAL_CAPABILITIES, LayoutFamily, LocaleStrategy, MIGRATION_CONTRACT_VERSION, MODEL_FIELD_ORDER, type MediaAsset, type MediaIngestInput, type MediaListOptions, type MediaListResult, type MediaProvider, type MediaUpdateInput, type MergeResult, MigrationHandoff, ModelDefinition, ModelKind, ModelSummary, NormalizePlan, NormalizePlanExtraction, NormalizePlanModel, NormalizePlanPatch, OfferProvider, PATH_PATTERNS, PaginationKind, Platform, PolymorphicRelationRef, ProjectGraph, ProjectIR, type ProviderCapabilities, QueryBinding, RawAcfValue, RawAttachment, RawAuthor, RawComment, RawIR, RawLanguagePair, RawMenu, RawMenuItem, RawMenuTarget, RawPost, RawProvenance, RawRedirect, RawSite, RawTerm, RawTermRef, type RemotePush, type RepoProvider, type RepoReader, type RepoWriter, RouteKind, RouteModel, RouteParamDef, RouteVariantRule, SECRET_PATTERNS, SLUG_PATTERN, SOURCE_ACCESS_LADDER, ScaffoldTemplate, ScanCandidate, ScanCandidatesResult, ScanSummaryResult, SingletonContentFile, SingletonMeta, SlotBinding, SlotKind, SourceAccessKind, StackType, StringContext, SyncResult, TITLE_FIELD_TYPES, ValidationError, ValidationResult, ViewportStrategy, Vocabulary, WorkflowMode, type WriteReadiness, canonicalStringify, conflictId, detectSecrets, generateEntryId, isMediaType, isTitleFieldType, orderedFieldNames, parseMarkdownFrontmatter, resolveFieldLabel, serializeMarkdownFrontmatter, sortKeys, stableHash, validateAccept, validateEntryId, validateFieldValue, validateLocale, validateSemanticType, validateSlug };
 //# sourceMappingURL=index.d.mts.map