@astryxdesign/core 0.6.2 → 0.6.3-canary.0788c49

package/src/Markdown/remark.ts

@@ -0,0 +1,1574 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file remark.ts
+ * @input Synchronous transform-only Remark plugins over the supported MDAST subset
+ * @output A Markdown transform that applies a validated round trip or fails closed
+ * @position Optional tree-shakeable compatibility adapter; never imported by Markdown
+ */
+
+import type {
+  MarkdownAstDataValue,
+  MarkdownAstExtensionNode,
+  MarkdownAstRoot,
+} from './ast';
+import {
+  isMarkdownPluginData,
+  type MarkdownTransform,
+  type MarkdownTransformContext,
+} from './plugins/protocol';
+import {isSafeMarkdownParserUrl} from './url';
+
+/* ------------------------------------------------------------------ *
+ * Public mutable tree the adapted plugin observes
+ * ------------------------------------------------------------------ */
+
+export interface MarkdownRemarkPoint {
+  line?: number;
+  column?: number;
+  offset?: number;
+}
+
+export interface MarkdownRemarkPosition {
+  start: MarkdownRemarkPoint;
+  end: MarkdownRemarkPoint;
+}
+
+export interface MarkdownRemarkNodeBase {
+  position?: MarkdownRemarkPosition;
+  data?: {[key: string]: unknown};
+}
+
+export interface MarkdownRemarkText extends MarkdownRemarkNodeBase {
+  type: 'text';
+  value: string;
+}
+
+export interface MarkdownRemarkInlineCode extends MarkdownRemarkNodeBase {
+  type: 'inlineCode';
+  value: string;
+}
+
+export interface MarkdownRemarkInlineMath extends MarkdownRemarkNodeBase {
+  type: 'inlineMath';
+  value: string;
+}
+
+export interface MarkdownRemarkBreak extends MarkdownRemarkNodeBase {
+  type: 'break';
+}
+
+export interface MarkdownRemarkPhrasingParent<
+  Type extends 'strong' | 'emphasis' | 'delete',
+> extends MarkdownRemarkNodeBase {
+  type: Type;
+  children: MarkdownRemarkPhrasingContent[];
+}
+
+export interface MarkdownRemarkLink extends MarkdownRemarkNodeBase {
+  type: 'link';
+  url: string;
+  /** Always `null` on input; a non-empty title cannot round-trip. */
+  title?: string | null;
+  children: MarkdownRemarkPhrasingContent[];
+}
+
+export interface MarkdownRemarkImage extends MarkdownRemarkNodeBase {
+  type: 'image';
+  url: string;
+  /** Always `null` on input; a non-empty title cannot round-trip. */
+  title?: string | null;
+  alt: string;
+}
+
+/** Astryx-owned citation. Read-only inside the adapter. */
+export interface MarkdownRemarkCitation extends MarkdownRemarkNodeBase {
+  type: 'citation';
+  sourceId: string;
+}
+
+/** Astryx-owned plugin extension node. Read-only inside the adapter. */
+export interface MarkdownRemarkExtension extends MarkdownRemarkNodeBase {
+  type: 'extension';
+  plugin: string;
+  name: string;
+  display: 'inline' | 'block';
+  source?: string;
+}
+
+export type MarkdownRemarkPhrasingContent =
+  | MarkdownRemarkText
+  | MarkdownRemarkInlineCode
+  | MarkdownRemarkInlineMath
+  | MarkdownRemarkBreak
+  | MarkdownRemarkPhrasingParent<'strong'>
+  | MarkdownRemarkPhrasingParent<'emphasis'>
+  | MarkdownRemarkPhrasingParent<'delete'>
+  | MarkdownRemarkLink
+  | MarkdownRemarkImage
+  | MarkdownRemarkCitation
+  | MarkdownRemarkExtension;
+
+export interface MarkdownRemarkHeading extends MarkdownRemarkNodeBase {
+  type: 'heading';
+  depth: 1 | 2 | 3 | 4 | 5 | 6;
+  children: MarkdownRemarkPhrasingContent[];
+}
+
+export interface MarkdownRemarkParagraph extends MarkdownRemarkNodeBase {
+  type: 'paragraph';
+  children: MarkdownRemarkPhrasingContent[];
+}
+
+export interface MarkdownRemarkCode extends MarkdownRemarkNodeBase {
+  type: 'code';
+  lang: string | null;
+  /** The authored info string after the language, `null` when absent. */
+  meta?: string | null;
+  value: string;
+}
+
+export interface MarkdownRemarkMath extends MarkdownRemarkNodeBase {
+  type: 'math';
+  value: string;
+}
+
+export interface MarkdownRemarkBlockquote extends MarkdownRemarkNodeBase {
+  type: 'blockquote';
+  children: MarkdownRemarkBlockContent[];
+}
+
+export interface MarkdownRemarkListItem extends MarkdownRemarkNodeBase {
+  type: 'listItem';
+  checked?: boolean | null;
+  /** Only a falsy value round-trips; Astryx has no loose-item contract. */
+  spread?: boolean | null;
+  children: MarkdownRemarkBlockContent[];
+}
+
+export interface MarkdownRemarkList extends MarkdownRemarkNodeBase {
+  type: 'list';
+  ordered: boolean;
+  start?: number | null;
+  spread?: boolean | null;
+  /** Astryx-preserved ordered-list marker delimiter. */
+  delimiter?: '.' | ')';
+  children: MarkdownRemarkListItem[];
+}
+
+export type MarkdownRemarkTableAlignment = 'left' | 'center' | 'right' | null;
+
+export interface MarkdownRemarkTableCell extends MarkdownRemarkNodeBase {
+  type: 'tableCell';
+  children: MarkdownRemarkPhrasingContent[];
+}
+
+export interface MarkdownRemarkTableRow extends MarkdownRemarkNodeBase {
+  type: 'tableRow';
+  children: MarkdownRemarkTableCell[];
+}
+
+export interface MarkdownRemarkTable extends MarkdownRemarkNodeBase {
+  type: 'table';
+  align: MarkdownRemarkTableAlignment[];
+  children: MarkdownRemarkTableRow[];
+}
+
+export interface MarkdownRemarkThematicBreak extends MarkdownRemarkNodeBase {
+  type: 'thematicBreak';
+}
+
+export type MarkdownRemarkBlockContent =
+  | MarkdownRemarkHeading
+  | MarkdownRemarkParagraph
+  | MarkdownRemarkCode
+  | MarkdownRemarkMath
+  | MarkdownRemarkBlockquote
+  | MarkdownRemarkList
+  | MarkdownRemarkTable
+  | MarkdownRemarkThematicBreak
+  | MarkdownRemarkImage
+  | MarkdownRemarkExtension;
+
+export interface MarkdownRemarkRoot extends MarkdownRemarkNodeBase {
+  type: 'root';
+  children: MarkdownRemarkBlockContent[];
+}
+
+/* ------------------------------------------------------------------ *
+ * Public constrained file and plugin shapes
+ * ------------------------------------------------------------------ */
+
+export interface MarkdownRemarkMessage {
+  reason: string;
+  fatal: boolean;
+  place: unknown;
+  ruleId: string | null;
+  toString(): string;
+}
+
+/**
+ * The isolated per-invocation file. It exposes readonly source text, finite
+ * JSON-like data, and diagnostics — never processor registration, cross-run
+ * state, a compiler, I/O, or asynchronous completion.
+ */
+export interface MarkdownRemarkFile {
+  readonly value: string;
+  readonly data: {[key: string]: unknown};
+  readonly messages: MarkdownRemarkMessage[];
+  message(
+    reason: string | Error,
+    place?: unknown,
+    ruleId?: string,
+  ): MarkdownRemarkMessage;
+  fail(reason: string | Error, place?: unknown, ruleId?: string): never;
+  toString(): string;
+}
+
+/**
+ * A Remark transformer either mutates the tree and returns nothing or returns
+ * a replacement root, and an attacher may legitimately return nothing at all.
+ * Both shapes have to stay assignable, so `void` belongs in these unions.
+ */
+// eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- see above
+type Returned<Value> = Value | undefined | void;
+
+export type MarkdownRemarkTransformer = (
+  tree: MarkdownRemarkRoot,
+  file: MarkdownRemarkFile,
+) => Returned<MarkdownRemarkRoot>;
+
+export type MarkdownRemarkPlugin<
+  Settings extends ReadonlyArray<unknown> = readonly [],
+> = (...settings: Settings) => Returned<MarkdownRemarkTransformer>;
+
+/**
+ * The structural shape a conventional Unified/Remark plugin already has. Its
+ * declared transformer may take Unified's callback parameter and may declare
+ * an asynchronous return union, so an existing typed plugin type-checks at the
+ * callsite without being rewritten. The adapter rejects an actual promise, and
+ * a callback-style transformer, at run time instead.
+ *
+ * Authoring a new plugin against Astryx? Annotate it with
+ * `MarkdownRemarkPlugin` to keep a typed tree and file.
+ */
+export type MarkdownRemarkCompatibleTransformer = (...args: never[]) => unknown;
+
+export type MarkdownRemarkCompatiblePlugin<
+  Settings extends ReadonlyArray<unknown> = readonly [],
+> = (...settings: Settings) => Returned<MarkdownRemarkCompatibleTransformer>;
+
+/* ------------------------------------------------------------------ *
+ * Internal helpers
+ * ------------------------------------------------------------------ */
+
+type UnknownRecord = Record<string, unknown>;
+
+/** Links a mutable copy back to the canonical node it was copied from. */
+const REMARK_ORIGIN = Symbol('astryx.markdown.remarkOrigin');
+
+/** hast escape channels; they are raw-markup sinks, not Markdown data. */
+const RAW_MARKUP_DATA_KEYS: ReadonlyArray<string> = [
+  'hName',
+  'hProperties',
+  'hChildren',
+];
+
+const PHRASING_TYPES = new Set([
+  'text',
+  'inlineCode',
+  'inlineMath',
+  'break',
+  'strong',
+  'emphasis',
+  'delete',
+  'link',
+  'image',
+  'citation',
+]);
+
+const BLOCK_TYPES = new Set([
+  'heading',
+  'paragraph',
+  'code',
+  'math',
+  'blockquote',
+  'list',
+  'table',
+  'thematicBreak',
+  'image',
+]);
+
+const PHRASING_PARENTS = new Set([
+  'heading',
+  'paragraph',
+  'strong',
+  'emphasis',
+  'delete',
+  'link',
+  'tableCell',
+]);
+
+const BLOCK_PARENTS = new Set(['root', 'blockquote', 'listItem']);
+
+const FIELDS_BY_TYPE: Readonly<Record<string, ReadonlyArray<string>>> = {
+  root: ['children'],
+  paragraph: ['children'],
+  heading: ['depth', 'children'],
+  blockquote: ['children'],
+  strong: ['children'],
+  emphasis: ['children'],
+  delete: ['children'],
+  tableRow: ['children'],
+  tableCell: ['children'],
+  text: ['value'],
+  inlineCode: ['value'],
+  inlineMath: ['value'],
+  math: ['value'],
+  code: ['lang', 'meta', 'value'],
+  link: ['url', 'title', 'children'],
+  image: ['url', 'title', 'alt'],
+  list: ['ordered', 'start', 'spread', 'delimiter', 'children'],
+  listItem: ['checked', 'spread', 'children'],
+  table: ['align', 'children'],
+  thematicBreak: [],
+  break: [],
+  citation: ['sourceId'],
+  extension: ['plugin', 'name', 'display', 'source'],
+};
+
+/**
+ * MDAST node kinds Astryx recognizes by name but deliberately does not
+ * support. Naming them makes a rejection actionable while keeping every
+ * diagnostic built from adapter-owned vocabulary only.
+ */
+const NAMED_UNSUPPORTED_TYPES: ReadonlySet<string> = new Set([
+  'html',
+  'yaml',
+  'toml',
+  'definition',
+  'footnote',
+  'footnoteDefinition',
+  'footnoteReference',
+  'imageReference',
+  'linkReference',
+  'containerDirective',
+  'leafDirective',
+  'textDirective',
+  'mdxjsEsm',
+  'mdxFlowExpression',
+  'mdxTextExpression',
+  'mdxJsxFlowElement',
+  'mdxJsxTextElement',
+]);
+
+/**
+ * VFile keys the profile knows about and refuses. Naming them makes the
+ * refusal actionable while keeping diagnostics free of plugin-chosen text.
+ */
+const NAMED_UNSUPPORTED_FILE_KEYS: ReadonlySet<string> = new Set([
+  'path',
+  'cwd',
+  'history',
+  'basename',
+  'dirname',
+  'extname',
+  'stem',
+  'stored',
+  'result',
+  'map',
+  'contents',
+]);
+
+/** The one reason reported when a plugin declares the document unsupported. */
+const FAILED_BY_PLUGIN = 'the plugin reported the document as unsupported';
+
+/**
+ * A closed rejection.
+ *
+ * Its reason is assembled only from this module's own constants, so it can
+ * never carry document source, plugin-authored text, or a plugin-chosen
+ * identifier — see `knownType` and `knownField`.
+ */
+class RemarkAdapterRejection extends Error {}
+
+/**
+ * The reason for each rejection this module raised, keyed by the thrown
+ * object.
+ *
+ * A plugin that catches one of our rejections can reach the class through
+ * `error.constructor` and throw a forgery, and `message` is writable on any
+ * Error — so neither the class nor the message is evidence. Only a throw this
+ * registry recorded is trusted, and its reason is read from here.
+ */
+const adapterReasons = new WeakMap<RemarkAdapterRejection, string>();
+
+/**
+ * Sticky failure state for the run currently on the stack.
+ *
+ * Every rejection this module raises is recorded here, not only on the throw:
+ * a plugin can wrap any adapter call in `try`/`catch` — a prohibited file
+ * read, a write, a `delete`, a processor access — and carry on as if it had
+ * not happened. The run must still fail, so the verdict lives somewhere the
+ * plugin cannot reach or rewrite.
+ *
+ * Runs never overlap: the adapter is synchronous and rejects anything
+ * asynchronous, so a single module-level slot is the whole story.
+ */
+let activeRun: RunState | null = null;
+
+interface RunState {
+  failed: boolean;
+  reason: string | null;
+}
+
+function createRunState(): RunState {
+  return {failed: false, reason: null};
+}
+
+function reject(reason: string): never {
+  if (activeRun != null && !activeRun.failed) {
+    activeRun.failed = true;
+    activeRun.reason = reason;
+  }
+  const rejection = new RemarkAdapterRejection(reason);
+  adapterReasons.set(rejection, reason);
+  throw rejection;
+}
+
+/**
+ * Runs `work` with `state` as the sticky failure target, restoring whatever
+ * was active before.
+ */
+function withRunState<Result>(state: RunState, work: () => Result): Result {
+  const previous = activeRun;
+  activeRun = state;
+  try {
+    return work();
+  } finally {
+    activeRun = previous;
+  }
+}
+
+/**
+ * Reports whether a value is thenable and, if it is, attaches a handler.
+ *
+ * An already-rejected promise with no handler becomes an unhandled rejection:
+ * it ends a Node SSR process by default, and its reason came from the plugin,
+ * so it would print document text the diagnostics work hard to keep out. The
+ * value is refused either way; attaching a handler only makes the refusal
+ * quiet.
+ *
+ * `then` is read exactly once. It may be a hostile getter — reading it can
+ * throw, or trip a guard of its own — so this never reads it a second time to
+ * re-ask the same question.
+ */
+function defuseThenable(value: unknown): boolean {
+  if (
+    (typeof value !== 'object' && typeof value !== 'function') ||
+    value === null
+  ) {
+    return false;
+  }
+  let then: unknown;
+  try {
+    then = (value as {then?: unknown}).then;
+  } catch {
+    // A `then` accessor that throws is a thenable-shaped hostile value.
+    return true;
+  }
+  if (typeof then !== 'function') {
+    return false;
+  }
+  try {
+    then.call(
+      value,
+      () => {},
+      () => {},
+    );
+  } catch {
+    // A `then` that throws when called is refused all the same.
+  }
+  return true;
+}
+
+/** Echoes a node type only when it is adapter-owned vocabulary. */
+function knownType(type: unknown): string {
+  return typeof type === 'string' &&
+    (Object.prototype.hasOwnProperty.call(FIELDS_BY_TYPE, type) ||
+      NAMED_UNSUPPORTED_TYPES.has(type))
+    ? type
+    : 'unknown';
+}
+
+/**
+ * Echoes a file key only when it is a name this module already documents —
+ * the supported surface, or an unsupported VFile key the profile explicitly
+ * names. A plugin-chosen key is never echoed.
+ */
+function knownFileKey(property: string | symbol): string {
+  const key = typeof property === 'symbol' ? 'unknown' : property;
+  return FILE_SURFACE.has(key) || NAMED_UNSUPPORTED_FILE_KEYS.has(key)
+    ? key
+    : 'unknown';
+}
+
+/** Echoes a field name only when it is adapter-owned vocabulary. */
+function knownField(type: string, field: string): string {
+  return field === 'position' ||
+    field === 'data' ||
+    field === 'type' ||
+    RAW_MARKUP_DATA_KEYS.includes(field) ||
+    (FIELDS_BY_TYPE[type]?.includes(field) ?? false)
+    ? field
+    : 'unknown';
+}
+
+function isPlainObject(value: unknown): value is UnknownRecord {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+const POINT_FIELDS: ReadonlyArray<string> = ['line', 'column', 'offset'];
+const POSITION_FIELDS: ReadonlyArray<string> = ['start', 'end'];
+
+function samePoint(left: unknown, right: unknown): boolean {
+  if (!isPlainObject(left) || !isPlainObject(right)) {
+    return false;
+  }
+  for (const point of [left, right]) {
+    for (const field of Object.keys(point)) {
+      if (!POINT_FIELDS.includes(field)) {
+        return false;
+      }
+    }
+  }
+  return POINT_FIELDS.every(field => left[field] === right[field]);
+}
+
+/**
+ * Exact provenance equality: every line, column, and offset on both points.
+ * Comparing offsets alone would let a shifted line or column through, and the
+ * adapter must never quietly restore Core's position over a changed one.
+ */
+function samePosition(left: unknown, right: unknown): boolean {
+  if (left === undefined || right === undefined) {
+    return left === right;
+  }
+  if (!isPlainObject(left) || !isPlainObject(right)) {
+    return false;
+  }
+  for (const position of [left, right]) {
+    for (const field of Object.keys(position)) {
+      if (!POSITION_FIELDS.includes(field)) {
+        return false;
+      }
+    }
+  }
+  return samePoint(left.start, right.start) && samePoint(left.end, right.end);
+}
+
+function copyPoint(point: unknown): MarkdownRemarkPoint | undefined {
+  if (!isPlainObject(point)) {
+    return undefined;
+  }
+  const copy: MarkdownRemarkPoint = {};
+  if (typeof point.line === 'number') {
+    copy.line = point.line;
+  }
+  if (typeof point.column === 'number') {
+    copy.column = point.column;
+  }
+  if (typeof point.offset === 'number') {
+    copy.offset = point.offset;
+  }
+  return copy;
+}
+
+function copyPosition(position: unknown): MarkdownRemarkPosition | undefined {
+  if (!isPlainObject(position)) {
+    return undefined;
+  }
+  const start = copyPoint(position.start);
+  const end = copyPoint(position.end);
+  return start == null || end == null ? undefined : {start, end};
+}
+
+function copyData<Value>(value: Value): Value {
+  if (Array.isArray(value)) {
+    const copy: unknown[] = [];
+    for (const entry of value) {
+      copy.push(copyData(entry));
+    }
+    return copy as Value;
+  }
+  if (isPlainObject(value)) {
+    const copy: UnknownRecord = {};
+    for (const [key, nested] of Object.entries(value)) {
+      copy[key] = copyData(nested);
+    }
+    return copy as Value;
+  }
+  return value;
+}
+
+function sameJsonValue(left: unknown, right: unknown): boolean {
+  if (left === right) {
+    return true;
+  }
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return (
+      left.length === right.length &&
+      left.every((item, index) => sameJsonValue(item, right[index]))
+    );
+  }
+  if (isPlainObject(left) && isPlainObject(right)) {
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+    return (
+      leftKeys.length === rightKeys.length &&
+      leftKeys.every(
+        key => key in right && sameJsonValue(left[key], right[key]),
+      )
+    );
+  }
+  return false;
+}
+
+/* ------------------------------------------------------------------ *
+ * Canonical tree → fresh mutable Remark tree
+ * ------------------------------------------------------------------ */
+
+interface OriginIndex {
+  readonly all: Set<UnknownRecord>;
+}
+
+function createOriginIndex(): OriginIndex {
+  return {all: new Set()};
+}
+
+function indexOrigin(node: UnknownRecord, index: OriginIndex): void {
+  index.all.add(node);
+}
+
+function toRemarkChildren(
+  children: unknown,
+  index: OriginIndex,
+): UnknownRecord[] {
+  return Array.isArray(children)
+    ? children.map(child => toRemarkNode(child as UnknownRecord, index))
+    : [];
+}
+
+function toRemarkNode(node: UnknownRecord, index: OriginIndex): UnknownRecord {
+  indexOrigin(node, index);
+  const copy: UnknownRecord = {type: node.type};
+  switch (node.type) {
+    case 'root':
+    case 'paragraph':
+    case 'blockquote':
+    case 'strong':
+    case 'emphasis':
+    case 'delete':
+    case 'tableRow':
+    case 'tableCell':
+    case 'listItem':
+      if (node.type === 'listItem' && typeof node.checked === 'boolean') {
+        copy.checked = node.checked;
+      }
+      copy.children = toRemarkChildren(node.children, index);
+      break;
+    case 'heading':
+      copy.depth = node.depth;
+      copy.children = toRemarkChildren(node.children, index);
+      break;
+    case 'text':
+    case 'inlineCode':
+    case 'inlineMath':
+    case 'math':
+      copy.value = node.value;
+      break;
+    case 'code':
+      copy.lang = node.lang ?? null;
+      // Astryx stores an absent info string as no key; MDAST spells it
+      // `null`. Both conversions translate, so authored fence metadata —
+      // which the semantic-fence helper reads — survives the round trip.
+      copy.meta = node.meta ?? null;
+      copy.value = node.value;
+      break;
+    case 'link':
+      copy.url = node.url;
+      copy.title = null;
+      copy.children = toRemarkChildren(node.children, index);
+      break;
+    case 'image':
+      copy.url = node.url;
+      copy.title = null;
+      copy.alt = node.alt;
+      break;
+    case 'list':
+      copy.ordered = node.ordered;
+      if (node.start !== undefined) {
+        copy.start = node.start;
+      }
+      if (node.spread !== undefined) {
+        copy.spread = node.spread;
+      }
+      if (node.delimiter !== undefined) {
+        copy.delimiter = node.delimiter;
+      }
+      copy.children = toRemarkChildren(node.children, index);
+      break;
+    case 'table':
+      copy.align = Array.isArray(node.align) ? [...node.align] : [];
+      copy.children = toRemarkChildren(node.children, index);
+      break;
+    case 'citation':
+      copy.sourceId = node.sourceId;
+      break;
+    case 'extension':
+      copy.plugin = node.plugin;
+      copy.name = node.name;
+      copy.display = node.display;
+      if (node.source !== undefined) {
+        copy.source = node.source;
+      }
+      break;
+    default:
+      break;
+  }
+  if (node.data !== undefined) {
+    copy.data = copyData(node.data);
+  }
+  const position = copyPosition(node.position);
+  if (position != null) {
+    copy.position = position;
+  }
+  // Enumerable so an immutable-style plugin that spreads a node keeps its
+  // provenance; symbol-keyed so it never reaches JSON, data, or rendering.
+  Object.defineProperty(copy, REMARK_ORIGIN, {
+    configurable: false,
+    enumerable: true,
+    value: node,
+    writable: false,
+  });
+  return copy;
+}
+
+/* ------------------------------------------------------------------ *
+ * Mutated Remark tree → validated canonical tree
+ * ------------------------------------------------------------------ */
+
+interface BackContext {
+  readonly index: OriginIndex;
+  readonly used: Set<UnknownRecord>;
+}
+
+/**
+ * Resolves the canonical node a transformed node came from.
+ *
+ * Provenance travels on an enumerable symbol the adapter puts on every copy,
+ * so a plugin that spreads a node (`{...node}`) keeps it. Nothing else counts:
+ * a node that merely looks like a source node — same position, same
+ * discriminants, rebuilt from scratch — is a forgery, not provenance, and is
+ * rejected rather than matched.
+ */
+function resolveOrigin(
+  node: UnknownRecord,
+  type: string,
+  context: BackContext,
+): UnknownRecord | null {
+  const linked = (node as {[REMARK_ORIGIN]?: unknown})[REMARK_ORIGIN];
+  if (linked === undefined) {
+    return null;
+  }
+  if (!isPlainObject(linked) || !context.index.all.has(linked)) {
+    reject(`a "${knownType(type)}" node carries forged provenance`);
+  }
+  if (linked.type !== type) {
+    reject(`a source "${knownType(linked.type)}" node cannot be retyped`);
+  }
+  if (context.used.has(linked)) {
+    reject(`a source "${knownType(type)}" node cannot be duplicated`);
+  }
+  context.used.add(linked);
+  return linked;
+}
+
+function assertKnownFields(type: string, node: UnknownRecord): void {
+  const allowed = FIELDS_BY_TYPE[type];
+  for (const key of Object.keys(node)) {
+    if (
+      key !== 'type' &&
+      key !== 'position' &&
+      key !== 'data' &&
+      !allowed.includes(key)
+    ) {
+      reject(
+        `a "${knownType(type)}" node cannot carry the unsupported field "${knownField(type, key)}"`,
+      );
+    }
+  }
+}
+
+function convertData(
+  type: string,
+  value: unknown,
+): MarkdownAstDataValue | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (isPlainObject(value)) {
+    for (const key of RAW_MARKUP_DATA_KEYS) {
+      if (key in value) {
+        reject(
+          `a "${knownType(type)}" node cannot carry the raw-markup data channel "${key}"`,
+        );
+      }
+    }
+  }
+  if (!isMarkdownPluginData(value)) {
+    reject(
+      `a "${knownType(type)}" node's data must be finite JSON-like values`,
+    );
+  }
+  return copyData(value);
+}
+
+function requireString(type: string, field: string, value: unknown): string {
+  if (typeof value !== 'string') {
+    reject(
+      `a "${knownType(type)}" node requires a string "${knownField(type, field)}"`,
+    );
+  }
+  return value;
+}
+
+function requireAbsentText(type: string, field: string, value: unknown): void {
+  if (value !== undefined && value !== null && value !== '') {
+    reject(
+      `a "${knownType(type)}" node's "${knownField(type, field)}" has no Astryx representation`,
+    );
+  }
+}
+
+function assertPlacement(
+  type: string,
+  node: UnknownRecord,
+  parentType: string | null,
+  insideLink: boolean,
+): void {
+  if (parentType == null) {
+    return;
+  }
+  if (type === 'root') {
+    reject('a document can only contain one root');
+  }
+  const display = type === 'extension' ? node.display : undefined;
+  const phrasing = PHRASING_TYPES.has(type) || display === 'inline';
+  const block = BLOCK_TYPES.has(type) || display === 'block';
+  if (
+    (PHRASING_PARENTS.has(parentType) && !phrasing) ||
+    (BLOCK_PARENTS.has(parentType) && !block) ||
+    (parentType === 'list' && type !== 'listItem') ||
+    (parentType === 'table' && type !== 'tableRow') ||
+    (parentType === 'tableRow' && type !== 'tableCell')
+  ) {
+    reject(
+      `a "${knownType(type)}" node cannot be a child of a "${knownType(parentType)}" node`,
+    );
+  }
+  if (insideLink && type === 'link') {
+    reject('a link cannot be nested inside another link');
+  }
+}
+
+function sameCanonicalFields(
+  origin: UnknownRecord,
+  fields: UnknownRecord,
+): boolean {
+  // Canonical nodes may carry explicitly undefined optional keys; an absent
+  // key and an undefined key mean the same thing.
+  const originKeys = Object.keys(origin).filter(
+    key => key !== 'type' && origin[key] !== undefined,
+  );
+  const fieldKeys = Object.keys(fields).filter(
+    key => fields[key] !== undefined,
+  );
+  if (originKeys.length !== fieldKeys.length) {
+    return false;
+  }
+  for (const key of fieldKeys) {
+    const next = fields[key];
+    const previous = origin[key];
+    if (next === previous) {
+      continue;
+    }
+    if (Array.isArray(next) && Array.isArray(previous)) {
+      if (
+        next.length !== previous.length ||
+        next.some((item, position) => item !== previous[position])
+      ) {
+        return false;
+      }
+      continue;
+    }
+    if (!sameJsonValue(next, previous)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function buildCanonicalNode(
+  type: string,
+  fields: UnknownRecord,
+  origin: UnknownRecord | null,
+): UnknownRecord {
+  if (origin != null && sameCanonicalFields(origin, fields)) {
+    return origin;
+  }
+  const built: UnknownRecord = {type, ...fields};
+  if (origin != null) {
+    // Carries Core's own enumerable symbol markers (source-heading identity)
+    // onto the replacement so Core still recognizes the node it authored.
+    for (const marker of Object.getOwnPropertySymbols(origin)) {
+      if (Object.prototype.propertyIsEnumerable.call(origin, marker)) {
+        Object.defineProperty(built, marker, {
+          configurable: false,
+          enumerable: true,
+          value: (origin as UnknownRecord & {[key: symbol]: unknown})[marker],
+          writable: false,
+        });
+      }
+    }
+  }
+  return built;
+}
+
+function fromRemarkChildren(
+  children: unknown,
+  type: string,
+  insideLink: boolean,
+  context: BackContext,
+): UnknownRecord[] {
+  if (!Array.isArray(children)) {
+    reject(`a "${knownType(type)}" node requires a children array`);
+  }
+  return children.map(child =>
+    fromRemarkNode(child, type, insideLink || type === 'link', context),
+  );
+}
+
+function fromRemarkNode(
+  value: unknown,
+  parentType: string | null,
+  insideLink: boolean,
+  context: BackContext,
+): UnknownRecord {
+  if (!isPlainObject(value)) {
+    reject('every transformed node must be a plain object');
+  }
+  const type = value.type;
+  if (typeof type !== 'string') {
+    reject('every transformed node requires a string type');
+  }
+  if (type === 'html') {
+    reject('raw HTML has no Astryx representation');
+  }
+  if (!(type in FIELDS_BY_TYPE)) {
+    reject(
+      `the node type "${knownType(type)}" is outside the supported MDAST subset`,
+    );
+  }
+  assertKnownFields(type, value);
+  assertPlacement(type, value, parentType, insideLink);
+
+  const origin = resolveOrigin(value, type, context);
+  if (origin == null) {
+    if (value.position !== undefined) {
+      reject(`a new "${knownType(type)}" node cannot carry a source position`);
+    }
+  } else if (!samePosition(value.position, origin.position)) {
+    // Covers a removed, rebuilt, offset-shifted, and line/column-shifted
+    // position alike. Core's position is never restored over a changed one.
+    reject(
+      `a source "${knownType(type)}" node's position must stay exactly as Core authored it`,
+    );
+  }
+
+  const fields: UnknownRecord = {};
+  switch (type) {
+    case 'root':
+    case 'paragraph':
+    case 'blockquote':
+    case 'strong':
+    case 'emphasis':
+    case 'delete':
+    case 'tableRow':
+    case 'tableCell':
+      fields.children = fromRemarkChildren(
+        value.children,
+        type,
+        insideLink,
+        context,
+      );
+      break;
+    case 'heading': {
+      const depth = value.depth;
+      if (
+        typeof depth !== 'number' ||
+        !Number.isInteger(depth) ||
+        depth < 1 ||
+        depth > 6
+      ) {
+        reject('a heading requires a depth between 1 and 6');
+      }
+      if (origin != null && origin.depth !== depth) {
+        reject("a source heading's depth cannot change");
+      }
+      fields.depth = depth;
+      fields.children = fromRemarkChildren(
+        value.children,
+        type,
+        insideLink,
+        context,
+      );
+      break;
+    }
+    case 'listItem': {
+      const checked = value.checked;
+      if (checked !== undefined && checked !== null) {
+        if (typeof checked !== 'boolean') {
+          reject('a list item requires a boolean "checked" value');
+        }
+        fields.checked = checked;
+      }
+      if (value.spread === true) {
+        reject('a loose list item has no Astryx representation');
+      }
+      fields.children = fromRemarkChildren(
+        value.children,
+        type,
+        insideLink,
+        context,
+      );
+      break;
+    }
+    case 'text':
+    case 'inlineCode':
+    case 'inlineMath':
+    case 'math':
+      fields.value = requireString(type, 'value', value.value);
+      break;
+    case 'code': {
+      const lang = value.lang;
+      if (lang !== undefined && lang !== null && typeof lang !== 'string') {
+        reject('a code node requires a string or null "lang"');
+      }
+      const meta = value.meta;
+      if (meta !== undefined && meta !== null && typeof meta !== 'string') {
+        reject('a code node requires a string or null "meta"');
+      }
+      fields.lang = lang ?? null;
+      if (meta != null && meta !== '') {
+        fields.meta = meta;
+      }
+      fields.value = requireString(type, 'value', value.value);
+      break;
+    }
+    case 'link': {
+      const url = requireString(type, 'url', value.url);
+      if (!isSafeMarkdownParserUrl(url)) {
+        reject('a link destination was rejected by the navigation owner');
+      }
+      requireAbsentText(type, 'title', value.title);
+      fields.url = url;
+      fields.children = fromRemarkChildren(
+        value.children,
+        type,
+        insideLink,
+        context,
+      );
+      break;
+    }
+    case 'image': {
+      const url = requireString(type, 'url', value.url);
+      if (!isSafeMarkdownParserUrl(url)) {
+        reject('an image source was rejected by the resource owner');
+      }
+      requireAbsentText(type, 'title', value.title);
+      if (typeof value.alt !== 'string') {
+        reject('an image requires its text alternative');
+      }
+      fields.url = url;
+      fields.alt = value.alt;
+      break;
+    }
+    case 'list': {
+      if (typeof value.ordered !== 'boolean') {
+        reject('a list requires a boolean "ordered" value');
+      }
+      fields.ordered = value.ordered;
+      const start = value.start;
+      if (start !== undefined && start !== null) {
+        if (typeof start !== 'number' || !Number.isFinite(start)) {
+          reject('a list requires a finite "start" value');
+        }
+        fields.start = start;
+      }
+      if (typeof value.spread === 'boolean') {
+        fields.spread = value.spread;
+      }
+      const delimiter = value.delimiter;
+      if (delimiter !== undefined) {
+        if (delimiter !== '.' && delimiter !== ')') {
+          reject('a list requires a "." or ")" delimiter');
+        }
+        fields.delimiter = delimiter;
+      }
+      fields.children = fromRemarkChildren(
+        value.children,
+        type,
+        insideLink,
+        context,
+      );
+      break;
+    }
+    case 'table': {
+      const align = value.align;
+      if (
+        !Array.isArray(align) ||
+        !align.every(
+          entry =>
+            entry === null ||
+            entry === 'left' ||
+            entry === 'center' ||
+            entry === 'right',
+        )
+      ) {
+        reject('a table requires normalized alignment values');
+      }
+      fields.align = [...align];
+      fields.children = fromRemarkChildren(
+        value.children,
+        type,
+        insideLink,
+        context,
+      );
+      break;
+    }
+    case 'thematicBreak':
+    case 'break':
+      break;
+    case 'citation':
+    case 'extension': {
+      // Astryx owns these outright: the adapter can show one to a plugin but
+      // never lets one be authored or edited, so every field must come back
+      // exactly as it went out.
+      const unchanged =
+        origin != null &&
+        sameJsonValue(value.data, origin.data) &&
+        (type === 'citation'
+          ? value.sourceId === origin.sourceId
+          : value.plugin === origin.plugin &&
+            value.name === origin.name &&
+            value.display === origin.display &&
+            value.source === origin.source);
+      if (!unchanged) {
+        reject(
+          `an Astryx "${knownType(type)}" node cannot be authored or changed here`,
+        );
+      }
+      // Equality across every owned field proves the node round-tripped, so
+      // the canonical node itself stays in place.
+      return origin;
+    }
+    default:
+      reject(
+        `the node type "${knownType(type)}" is outside the supported MDAST subset`,
+      );
+  }
+
+  const data = convertData(type, value.data);
+  if (data !== undefined) {
+    fields.data = data;
+  }
+  if (origin != null && origin.position !== undefined) {
+    fields.position = origin.position;
+  }
+
+  const node = buildCanonicalNode(type, fields, origin);
+  if (type === 'table' && node !== origin) {
+    const rows = fields.children as UnknownRecord[];
+    const width = (rows[0]?.children as unknown[] | undefined)?.length ?? 0;
+    if (
+      rows.some(
+        row => (row.children as unknown[] | undefined)?.length !== width,
+      )
+    ) {
+      reject('a transformed table cannot have ragged rows');
+    }
+  }
+  return node;
+}
+
+/* ------------------------------------------------------------------ *
+ * Constrained file and processor guard
+ * ------------------------------------------------------------------ */
+
+function createMessage(
+  reason: string | Error,
+  place: unknown,
+  ruleId: string | undefined,
+): MarkdownRemarkMessage {
+  const text = reason instanceof Error ? reason.message : reason;
+  return {
+    reason: text,
+    fatal: false,
+    place: place ?? null,
+    ruleId: ruleId ?? null,
+    toString() {
+      return text;
+    },
+  };
+}
+
+/**
+ * The documented surface of the constrained file. Everything else — `path`,
+ * `cwd`, `history`, `basename`, `dirname`, `extname`, `stem`, `stored`, and
+ * any other key — is unsupported: the adapter has no filesystem, no processor,
+ * and no run history to answer with.
+ */
+const FILE_SURFACE: ReadonlySet<string> = new Set([
+  'value',
+  'data',
+  'messages',
+  'message',
+  'fail',
+  'toString',
+]);
+
+/**
+ * Adapter-owned data for one invocation.
+ *
+ * It lives here rather than on the file the plugin holds, because everything
+ * the plugin can reach it can also rewrite — a plugin must not be able to
+ * fake a `fatal` message or hide one it caused. The failure verdict itself
+ * belongs to the run (`RunState`), which every rejection records.
+ */
+interface FileState {
+  readonly data: UnknownRecord;
+}
+
+function createConstrainedFile(source: string): {
+  readonly file: MarkdownRemarkFile;
+  readonly state: FileState;
+} {
+  const messages: MarkdownRemarkMessage[] = [];
+  const state: FileState = {data: {}};
+  const target: MarkdownRemarkFile = {
+    get value() {
+      return source;
+    },
+    get data() {
+      return state.data;
+    },
+    get messages() {
+      return messages;
+    },
+    message(reason, place, ruleId) {
+      const message = createMessage(reason, place, ruleId);
+      messages.push(message);
+      return message;
+    },
+    fail(reason, place, ruleId) {
+      const message = createMessage(reason, place, ruleId);
+      message.fatal = true;
+      messages.push(message);
+      // `reject` records the verdict in run state, so a plugin that catches
+      // this and carries on has still declared the document unsupported and
+      // the run cannot succeed behind its back.
+      reject(FAILED_BY_PLUGIN);
+    },
+    toString() {
+      return source;
+    },
+  };
+
+  // Fails closed on every unsupported read and on every write. Returning
+  // `undefined` for `file.cwd` would let a plugin silently take a path that
+  // depends on a capability this profile does not have.
+  /* eslint-disable @typescript-eslint/promise-function-async -- these are
+     Proxy traps, not async work; the adapter is synchronous throughout. */
+  const file = new Proxy(target, {
+    get(_target, property, receiver) {
+      if (typeof property === 'symbol') {
+        // JS protocol (inspection, iteration, `instanceof`), not VFile
+        // surface. Answering `undefined` here cannot mislead a plugin.
+        return Reflect.get(target, property, receiver) as unknown;
+      }
+      if (!FILE_SURFACE.has(property)) {
+        reject(`the file has no "${knownFileKey(property)}" in this profile`);
+      }
+      return Reflect.get(target, property, receiver) as unknown;
+    },
+    set(_target, property) {
+      reject(
+        `the file's "${knownFileKey(property)}" cannot be assigned in this profile`,
+      );
+    },
+    defineProperty(_target, property) {
+      reject(
+        `the file's "${knownFileKey(property)}" cannot be assigned in this profile`,
+      );
+    },
+    deleteProperty(_target, property) {
+      reject(
+        `the file's "${knownFileKey(property)}" cannot be assigned in this profile`,
+      );
+    },
+    // Truthfully answers "no such capability" so a plugin that feature-detects
+    // can take its own graceful path instead of being rejected.
+    has(_target, property) {
+      return typeof property === 'symbol' || FILE_SURFACE.has(property);
+    },
+    ownKeys() {
+      return [...FILE_SURFACE];
+    },
+    getOwnPropertyDescriptor(_target, property) {
+      return typeof property !== 'symbol' && !FILE_SURFACE.has(property)
+        ? undefined
+        : Reflect.getOwnPropertyDescriptor(target, property);
+    },
+  });
+  /* eslint-enable @typescript-eslint/promise-function-async */
+
+  return {file, state};
+}
+
+/**
+ * Stands in for Unified's processor. Any access fails closed, so parser,
+ * compiler, and cross-run `data()` registration cannot be mistaken for
+ * supported behavior.
+ */
+const PROCESSOR_ACCESS = 'processor registration is outside the adapter';
+
+const processorGuard: unknown = new Proxy(Object.freeze({}), {
+  get() {
+    reject(PROCESSOR_ACCESS);
+  },
+  set() {
+    reject(PROCESSOR_ACCESS);
+  },
+  defineProperty() {
+    reject(PROCESSOR_ACCESS);
+  },
+  deleteProperty() {
+    reject(PROCESSOR_ACCESS);
+  },
+  apply() {
+    reject(PROCESSOR_ACCESS);
+  },
+  has() {
+    // Truthful: this stand-in offers no processor capability at all.
+    return false;
+  },
+  ownKeys() {
+    return [];
+  },
+});
+
+/* ------------------------------------------------------------------ *
+ * Public adapter
+ * ------------------------------------------------------------------ */
+
+/**
+ * The one reason reported for a failed run.
+ *
+ * A rejection's reason is built from this module's own vocabulary, so it is
+ * safe to report. Anything a plugin authored — a thrown error's message, a
+ * `file.fail()` reason, a `file.message()` diagnostic — is not: the plugin
+ * read the document, so its text may quote it. Those stay on the file, which
+ * only the plugin sees.
+ */
+function describeFailure(error: unknown): string {
+  const reason =
+    error instanceof RemarkAdapterRejection
+      ? adapterReasons.get(error)
+      : undefined;
+  return reason ?? 'the plugin threw an error';
+}
+
+/**
+ * Adapt one synchronous transform-only Remark plugin to a Markdown transform.
+ *
+ * The adapted plugin receives a fresh mutable copy of the canonical document
+ * and an isolated constrained file. Every returned or mutated tree round-trips
+ * through the supported MDAST subset before it becomes observable; anything
+ * unsupported — a parser or compiler plugin, asynchronous work, processor
+ * state, raw HTML, an unsupported node, a forged position, or unrepresentable
+ * metadata — keeps the last valid document and reports one diagnostic.
+ *
+ * Compatibility is per plugin and proven by fixtures, never inferred from a
+ * package name.
+ *
+ * @example
+ * ```
+ * import {createMarkdownPlugin} from '@astryxdesign/core/Markdown';
+ * import {createMarkdownRemarkTransform} from '@astryxdesign/core/Markdown/remark';
+ *
+ * const shouting = createMarkdownPlugin({
+ *   name: 'shouting-headings',
+ *   apiVersion: 1,
+ *   transform: createMarkdownRemarkTransform(remarkShoutingHeadings),
+ * });
+ * ```
+ */
+export function createMarkdownRemarkTransform<
+  Settings extends ReadonlyArray<unknown> = readonly [],
+>(
+  plugin: MarkdownRemarkPlugin<Settings>,
+  ...settings: Settings
+): MarkdownTransform<never>;
+export function createMarkdownRemarkTransform<
+  Settings extends ReadonlyArray<unknown> = readonly [],
+>(
+  plugin: MarkdownRemarkCompatiblePlugin<Settings>,
+  ...settings: Settings
+): MarkdownTransform<never>;
+export function createMarkdownRemarkTransform(
+  plugin: MarkdownRemarkCompatiblePlugin<ReadonlyArray<unknown>>,
+  ...settings: ReadonlyArray<unknown>
+): MarkdownTransform<never> {
+  if (typeof plugin !== 'function') {
+    throw new TypeError('Markdown Remark adapter: plugin must be a function');
+  }
+
+  let attached = false;
+  let transformer: MarkdownRemarkTransformer | null = null;
+  let attachFailure: string | null = null;
+
+  const attach = (): void => {
+    attached = true;
+    // The attacher can touch the processor guard and catch the rejection, so
+    // it gets its own sticky state; a swallowed capability access is still a
+    // failed attach.
+    const attachState = createRunState();
+    withRunState(attachState, () => {
+      try {
+        const created = (
+          plugin as (this: unknown, ...args: ReadonlyArray<unknown>) => unknown
+        ).apply(processorGuard, settings as unknown as unknown[]);
+        // Defuse before any verdict: an attacher that both tripped a guard
+        // and returned a rejected promise must not leave that promise
+        // unhandled just because the guard is reported instead.
+        const attacherIsAsync = defuseThenable(created);
+        if (attachState.failed) {
+          reject(attachState.reason ?? FAILED_BY_PLUGIN);
+        }
+        if (attacherIsAsync) {
+          reject('an asynchronous plugin is outside the adapter');
+        }
+        if (typeof created !== 'function') {
+          attachFailure =
+            'only a transform-only plugin returning one synchronous transformer is supported';
+          return;
+        }
+        if (created.length >= 3) {
+          attachFailure =
+            'a callback-style (asynchronous) transformer is outside the adapter';
+          return;
+        }
+        transformer = created as MarkdownRemarkTransformer;
+      } catch (error) {
+        attachFailure = describeFailure(error);
+      }
+    });
+    if (attachState.failed && attachFailure == null) {
+      attachFailure = attachState.reason;
+      transformer = null;
+    }
+  };
+
+  return (
+    document: MarkdownAstRoot<MarkdownAstExtensionNode>,
+    context: MarkdownTransformContext,
+  ): MarkdownAstRoot<MarkdownAstExtensionNode> => {
+    if (!attached) {
+      attach();
+    }
+    const runner = transformer;
+    if (runner == null) {
+      context.report(`Remark adapter: ${attachFailure ?? 'the plugin failed'}`);
+      return document;
+    }
+
+    const index = createOriginIndex();
+    const {file, state} = createConstrainedFile(context.source);
+    const run = createRunState();
+
+    return withRunState(run, () => {
+      try {
+        const tree = toRemarkNode(
+          document as unknown as UnknownRecord,
+          index,
+        ) as unknown as MarkdownRemarkRoot;
+        const returned = runner(tree, file);
+        // Defuse first, whatever else is wrong. A transformer that both
+        // swallowed a guard refusal and returned a rejected promise still
+        // gets that promise handled — the sticky verdict decides only what
+        // is *reported*, never whether the promise is left dangling.
+        const returnedIsAsync = defuseThenable(returned);
+        if (run.failed) {
+          // The plugin tripped a guard — a prohibited file key, a processor
+          // access, its own fail() — and swallowed the rejection. The verdict
+          // stands, and its original reason is the one reported.
+          reject(run.reason ?? FAILED_BY_PLUGIN);
+        }
+        if (returnedIsAsync) {
+          reject('an asynchronous transformer is outside the adapter');
+        }
+        const output = returned ?? tree;
+        if (!isMarkdownPluginData(state.data)) {
+          reject('file data must be finite JSON-like values');
+        }
+
+        const back: BackContext = {index, used: new Set()};
+        const root = fromRemarkNode(output, null, false, back);
+        if (root.type !== 'root') {
+          reject('a transformer must return the document root');
+        }
+        const children = root.children as UnknownRecord[];
+        if (
+          context.display === 'inline' &&
+          (children.length !== 1 || children[0]?.type !== 'paragraph')
+        ) {
+          reject(
+            'an inline document must stay one paragraph of phrasing content',
+          );
+        }
+        if (run.failed) {
+          // Last word before the output becomes observable. A guard can fire
+          // after the earlier check — a hostile `then` accessor, a getter on
+          // a returned node — and a refusal the plugin caught must never end
+          // with its output accepted.
+          reject(run.reason ?? FAILED_BY_PLUGIN);
+        }
+        return root as unknown as MarkdownAstRoot<MarkdownAstExtensionNode>;
+      } catch (error) {
+        // Exactly one report per failed run, and never a second for the
+        // plugin's own messages — see `describeFailure`. The first recorded
+        // rejection outranks a later error, so swallowing one and throwing
+        // something friendlier cannot change what is reported.
+        context.report(
+          `Remark adapter: ${run.reason ?? describeFailure(error)}`,
+        );
+        return document;
+      }
+    });
+  };
+}