@glw907/cairn-cms 0.62.2 → 0.76.0

package/src/lib/content/reference-index.ts

@@ -0,0 +1,159 @@
+// cairn-cms: the cross-branch reference index, the where-referenced core of the rename and delete
+// gates. It answers "which entries reference this target entry" for every reference edge, keyed by the
+// target's (concept, id) PAIR. The key is the pair and never an id alone (unlike media/usage.ts, which
+// keys on a globally-unique content hash), because an id is unique only within a concept: pages/about
+// and posts/about are distinct targets, and reverse-mapping by id alone would cross that boundary and
+// refuse a rename or delete on a phantom inbound. The map unions two sources: the published corpus on
+// main and every open cairn/* edit branch, so a target referenced only in an unpublished draft still
+// counts as referenced and is not mistaken for safe to delete or freely rename.
+//
+// The main arm reads the content manifest's per-entry references (the edges manifestEntryFromFile
+// records) and builds the reverse map; it never crawls the files, since the manifest already carries
+// the edges. The branch arm cannot use a manifest (the content manifest is never committed to a
+// branch), so it reconstructs each edited entry's path from the branch name, reads that one file, and
+// runs the schema extractor directly.
+import type { ConceptDescriptor } from './types.js';
+import type { Backend } from '../github/backend.js';
+import type { Manifest } from './manifest.js';
+import { PENDING_PREFIX, parsePendingBranch } from './pending.js';
+import { findConcept } from './concepts.js';
+import { isValidId, filenameFromId } from './ids.js';
+import { parseMarkdown } from './frontmatter.js';
+import { extractReferenceEdges } from './references.js';
+
+/**
+ * Where a reference lives: the published corpus on main, or a named open edit branch. Re-declared here
+ *  (rather than imported from media/usage.ts) so the content layer does not depend on the media layer.
+ */
+export type UsageOrigin = { kind: 'published' } | { kind: 'branch'; branch: string };
+
+/** One entry that references a target, in a shape the rename and delete gates name and group by. */
+export interface ReferenceUsageEntry {
+  /** The referencing (source) entry's concept id, e.g. "posts". */
+  concept: string;
+  /** The referencing (source) entry's id (its filename stem). */
+  id: string;
+  /** The referencing entry's title for display, from the manifest (published) or frontmatter (branch). */
+  title: string;
+  /** The referencing entry's public permalink, present for a published entry (carried from the manifest). */
+  permalink?: string;
+  /** The frontmatter field the edge was declared on. */
+  field: string;
+  /** Published vs the cairn/* branch the edit lives on. */
+  origin: UsageOrigin;
+}
+
+/**
+ * The target's `${concept}/${id}` pair to the distinct entries that reference it. A pair with no row is
+ *  not referenced anywhere the index could read (main plus the listed open branches).
+ */
+export type ReferenceIndex = Map<string, ReferenceUsageEntry[]>;
+
+/**
+ * Build options. `branches` lets a caller that already listed the open cairn/* branches pass them in so
+ *  the index does not list them a second time. `strict` flips the per-branch read from degrade-and-skip
+ *  to fail-closed: a delete or rename gate must not treat a transient branch-read failure as an absent
+ *  reference, so it rethrows instead.
+ */
+export interface BuildReferenceOptions {
+  /** The open cairn/* branch names, already listed. When present the index skips its own listing. */
+  branches?: string[];
+  /** When true a branch read that throws rejects the whole build, so the caller can fail closed. */
+  strict?: boolean;
+}
+
+/** Append a row under its target pair key, creating the bucket on first use. */
+function push(index: ReferenceIndex, key: string, entry: ReferenceUsageEntry): void {
+  const rows = index.get(key);
+  if (rows) rows.push(entry);
+  else index.set(key, [entry]);
+}
+
+/**
+ * Build the pair-keyed reference index over main (from the manifest's per-entry references) plus every
+ * open cairn/* branch (parsed from its edited markdown).
+ *
+ * By default a single branch read that throws degrades that one branch and is skipped, the way the
+ * admin loaders degrade a failed read. That tolerance is wrong for the rename and delete gates: a
+ * transient branch-read failure would make a still-referenced target look free. Pass `strict: true` to
+ * rethrow a branch failure so the caller fails closed. Pass `branches` to reuse a branch list the
+ * caller already has rather than listing them a second time.
+ */
+export async function buildReferenceIndex(
+  backend: Backend,
+  concepts: ConceptDescriptor[],
+  manifest: Manifest,
+  opts: BuildReferenceOptions = {},
+): Promise<ReferenceIndex> {
+  const index: ReferenceIndex = new Map();
+
+  // The main arm: the manifest already carries each entry's reference edges, so this is a pure reverse
+  // map with no per-file read. The KEY is the edge's TARGET (concept, id); the ROW is the source entry.
+  for (const entry of manifest.entries) {
+    for (const edge of entry.references ?? []) {
+      push(index, `${edge.concept}/${edge.id}`, {
+        concept: entry.concept,
+        id: entry.id,
+        title: entry.title,
+        permalink: entry.permalink,
+        field: edge.field,
+        origin: { kind: 'published' },
+      });
+    }
+  }
+
+  // The branch arm: read each open cairn/* branch's one edited file. The path is derivable from the
+  // branch name, so no tree-listing is needed. The branch list is reused when the caller passes it.
+  const names = opts.branches ?? (await backend.listBranches(PENDING_PREFIX));
+  // Read the branches in parallel rather than one at a time, so the latency floor is one round trip
+  // instead of N. workerd self-throttles to 6 simultaneous outbound connections, so this batch and
+  // the load path's media-union and linker reads each stay under the limit; do NOT run this fan-out
+  // concurrently with those (a future combined safety gate must not wrap them in one Promise.all),
+  // since the merged fan-out would queue behind that throttle.
+  const perBranch = await Promise.all(
+    names.map(async (name): Promise<{ key: string; entry: ReferenceUsageEntry }[]> => {
+      // Resolve the branch name to a configured entry with the same guard the branch tooling uses: a
+      // malformed name, an id that fails the slug rule (entry paths are built from it, so this is the
+      // path confinement), or a concept this site does not configure is skipped, no read attempted.
+      const ref = parsePendingBranch(name);
+      if (!ref || !isValidId(ref.id)) return [];
+      const concept = findConcept(concepts, ref.concept);
+      if (!concept) return [];
+
+      const path = `${concept.dir}/${filenameFromId(ref.id)}`;
+      try {
+        const raw = await backend.readFile(path, name);
+        if (raw === null) return []; // The file is absent on the branch: nothing to extract.
+        const { frontmatter } = parseMarkdown(raw);
+        const fmTitle = frontmatter.title;
+        const title = typeof fmTitle === 'string' && fmTitle.trim() ? fmTitle : ref.id;
+        const rows: { key: string; entry: ReferenceUsageEntry }[] = [];
+        for (const edge of extractReferenceEdges(frontmatter, concept.fields)) {
+          rows.push({
+            key: `${edge.concept}/${edge.id}`,
+            entry: {
+              concept: concept.id,
+              id: ref.id,
+              title,
+              field: edge.field,
+              origin: { kind: 'branch', branch: name },
+            },
+          });
+        }
+        return rows;
+      } catch (err) {
+        // In strict mode a branch failure fails the whole build so the gate can fail closed; otherwise
+        // degrade this one branch rather than sinking the screen.
+        if (opts.strict) throw err;
+        return [];
+      }
+    }),
+  );
+
+  // Fold the per-branch rows back in, preserving the branch order so the index reads stably.
+  for (const rows of perBranch) {
+    for (const { key, entry } of rows) push(index, key, entry);
+  }
+
+  return index;
+}

package/src/lib/content/standard-schema.ts

@@ -0,0 +1,25 @@
+// cairn-cms: the Standard Schema conformance types, shared by both the v1 schema and the v2
+// fieldset validators. They live here, apart from either validator, so the v2 `fieldset` keeps
+// importing them once the v1 `schema.ts` is removed at the Contract v2 cutover.
+
+/** The validate input the cairn adapter takes: the raw frontmatter and the body. */
+export interface StandardInput {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+/**
+ * A minimal local copy of the Standard Schema v1 interface (https://standardschema.dev), so the
+ *  schema is a drop-in where the ecosystem accepts a validator, with no runtime dependency.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardResult<Output>;
+    readonly types?: { readonly input: Input; readonly output: Output };
+  };
+}
+type StandardResult<Output> =
+  | { readonly value: Output; readonly issues?: undefined }
+  | { readonly issues: ReadonlyArray<{ readonly message: string; readonly path?: ReadonlyArray<PropertyKey> }> };

package/src/lib/content/types.ts

@@ -9,107 +9,14 @@
 // boundary to the editor form.
 import type { ComponentRegistry } from '../render/registry.js';
 import type { IconSet } from '../render/glyph.js';
+import type { IslandRegistry } from '../islands/types.js';
+import type { BackendProvider } from '../github/backend.js';
 import type { DatePrefix } from './ids.js';
-import type { ConceptSchema } from './schema.js';
+import type { Fieldset } from './fieldset.js';
+import type { FieldDescriptor } from './fields.js';
 import type { LinkResolve } from './links.js';
 import type { VariantSpec } from '../media/transform-url.js';
 
-/** Common to every frontmatter field: the frontmatter key, the form label, and whether it is required. */
-interface FieldBase {
-  /** Frontmatter key and form input name. */
-  name: string;
-  /** Form label. */
-  label: string;
-  /** A required field fails validation when empty (spec §7.4). */
-  required?: boolean;
-  /**
-   * One author-facing sentence shown under the field in the editor, in plain end-user language.
-   * Optional; render nothing when absent. Not a validation rule.
-   */
-  description?: string;
-}
-
-/** A single-line text input. */
-export interface TextField extends FieldBase {
-  type: 'text';
-  /** Minimum character length of a non-empty value. */
-  min?: number;
-  /** Maximum character length. */
-  max?: number;
-  /** Exact required character length. */
-  length?: number;
-  /**
-   * A regular-expression source string the value must match. Stored as a string so the field
-   *  list stays plain serializable data; the validator compiles it.
-   */
-  pattern?: string;
-}
-/** A multi-line text input. */
-export interface TextareaField extends FieldBase {
-  type: 'textarea';
-  /** Visible rows; the editor picks a default when omitted. */
-  rows?: number;
-  /** Minimum character length of a non-empty value. */
-  min?: number;
-  /** Maximum character length. */
-  max?: number;
-  /** Exact required character length. */
-  length?: number;
-  /** A regular-expression source string the value must match. */
-  pattern?: string;
-}
-/** A `YYYY-MM-DD` date input. */
-export interface DateField extends FieldBase {
-  type: 'date';
-  /** Earliest allowed date, as `YYYY-MM-DD`. */
-  min?: string;
-  /** Latest allowed date, as `YYYY-MM-DD`. */
-  max?: string;
-}
-/** A checkbox; absent means false. */
-export interface BooleanField extends FieldBase {
-  type: 'boolean';
-}
-/** A closed-vocabulary tag set, rendered as checkboxes (ecnordic). */
-export interface TagsField extends FieldBase {
-  type: 'tags';
-  /** The controlled vocabulary. */
-  options: readonly string[];
-}
-/** Free-form tags, edited as one comma-separated input (907). */
-export interface FreeTagsField extends FieldBase {
-  type: 'freetags';
-  placeholder?: string;
-}
-/**
- * A hero image set in frontmatter. The stored value is the nested object
- * `{ src: string; alt: string; caption?: string }`, where `src` is a 2b `media:` reference, `alt`
- * is the screen-reader description, and `caption` is an optional line the site template may show.
- * One image serves two jobs: the template's lead image and the social-card image. The field feeding
- * the social card is the `seo`-flagged one, defaulting to the field named `image`; a concept declares
- * at most one SEO image field.
- */
-export interface ImageField extends FieldBase {
-  type: 'image';
-  /** Whether this field feeds the social-card image. The field named `image` defaults to true. */
-  seo?: boolean;
-}
-
-/**
- * The discriminated union the per-concept frontmatter form is generated from. A scalar field type
- * is one variant here plus one decode arm in `frontmatterFromForm` and one in `validateFields`. The
- * structured `image` field additionally needs a read-back arm in `formValues` and a type-inference
- * arm in `schema.ts`, since its value is a nested object rather than a single string.
- */
-export type FrontmatterField =
-  | TextField
-  | TextareaField
-  | DateField
-  | BooleanField
-  | TagsField
-  | FreeTagsField
-  | ImageField;
-
 /**
  * The stored value of an `image` field: a `media:` reference, a screen-reader description, and an
  *  optional caption.
@@ -122,59 +29,75 @@ export interface ImageValue {
   decorative?: boolean;
 }
 
+/** One validation failure located by a path: a top-level key, then a row index and/or a leaf sub-key. */
+export interface ValidationIssue {
+  /** The path to the failing field, e.g. ['faq', 0, 'question'] or ['address', 'city'] or ['title']. */
+  path: (string | number)[];
+  /** The author-facing message, naming the field's label. */
+  message: string;
+}
+
 /**
- * A validator's verdict. On success it carries the normalized frontmatter to commit; on
- * failure it carries field-keyed error messages (the empty key is a form-level error).
- * Invalid input bounces to the form and never reaches git (spec §7.4).
+ * A validator's verdict. On success it carries the normalized frontmatter to commit; on failure it
+ * carries field-keyed error messages (the empty key is a form-level error) and, additively, the
+ * located `issues` with multi-segment paths so the form can route a nested-container error to the
+ * right input. Invalid input bounces to the form and never reaches git (spec §7.4).
  */
 export type ValidationResult =
   | { ok: true; data: Record<string, unknown> }
-  | { ok: false; errors: Record<string, string> };
+  | { ok: false; errors: Record<string, string>; issues?: ValidationIssue[] };
+
+/**
+ * A field descriptor with its frontmatter key re-attached as `name`. This is the normalized form
+ *  `ConceptDescriptor.fields` carries: `normalizeConcepts` derives it from a concept's `fieldset`
+ *  record so every consumer (the editor form, the form decoder, the media extractor) iterates an
+ *  array and reads `name` rather than the keyed record.
+ */
+export type NamedField = FieldDescriptor & { name: string };
 
 /**
- * Per-site configuration for one content concept (spec §8). One `schema`, built with
- * `defineFields`, is the single source of truth for the editor form, the validator, and the
- * inferred frontmatter type. Generic over the schema so a concept's concrete type survives for
- * typed reads. Concept-fixed behavior such as routability is not here; it lives in the engine's
- * routing table (`CONCEPT_ROUTING`).
+ * Per-site configuration for one content concept (spec §8). One `fields` fieldset, built with
+ * `fieldset`, is the single source of truth for the editor form, the validator, and the
+ * inferred frontmatter type. Generic over the fieldset so a concept's concrete type survives for
+ * typed reads. A concept also declares its own routing and URL policy here (`routing`, `permalink`,
+ * `datePrefix`), resolved by `normalizeConcepts`.
  */
-export interface ConceptConfig<S extends ConceptSchema = ConceptSchema> {
+export interface ConceptConfig<S extends Fieldset = Fieldset> {
   /** Repo-relative content directory, e.g. "src/content/posts". */
   dir: string;
   /** Sidebar label; defaults from the concept id when omitted. */
   label?: string;
   /** The singular noun for the create affordances ("New post"); defaults to `label` when omitted. */
   singular?: string;
-  /** The concept's schema: the form projection, the generated validator, and the inferred type. */
-  schema: S;
+  /** The concept's fieldset: the form projection, the generated validator, and the inferred type. */
+  fields: S;
+  /**
+   * This concept's routing. A named shorthand (`'feed'` dated and in feeds, `'page'` a routable
+   *  static page, `'embedded'` not routable) or an explicit rule. Omitted means `'page'`.
+   */
+  routing?: 'feed' | 'page' | 'embedded' | RoutingRule;
+  /** The permalink pattern, root-relative, e.g. `/blog/:year/:slug`. Defaults by concept id. */
+  permalink?: string;
+  /** Date-prefix granularity for a dated concept's id-to-slug stripping. Defaults to `day`. */
+  datePrefix?: DatePrefix;
   /**
    * Frontmatter keys to surface on each `ContentSummary.fields`, so a list card reads an authored
-   *  field without a per-entry detail read. Each key should also be declared in `schema`.
+   *  field without a per-entry detail read. Each key should also be declared in `fields`.
    */
   summaryFields?: string[];
 }
 
 /**
- * A concept's URL policy, set per concept in the YAML site-config (not the adapter). `permalink` is
- * a `/`-prefixed pattern of literal segments and the tokens `:slug`, `:year`, `:month`, `:day`.
- * `datePrefix` is the filename date-prefix granularity for a dated concept. Both default in
- * `normalizeConcepts` when omitted.
+ * A concept's URL policy, declared on the adapter concept itself (`ConceptConfig.permalink` and
+ * `ConceptConfig.datePrefix`) since Contract v2. `permalink` is a `/`-prefixed pattern of literal
+ * segments and the tokens `:slug`, `:year`, `:month`, `:day`. `datePrefix` is the filename
+ * date-prefix granularity for a dated concept. Both default in `normalizeConcepts` when omitted.
  */
 export interface ConceptUrlPolicy {
   permalink?: string;
   datePrefix?: DatePrefix;
 }
 
-/** The GitHub App backend a site reads from and commits to (spec §8). Plain data the GitHub engine (Plan 03) consumes. */
-export interface BackendConfig {
-  owner: string;
-  repo: string;
-  /** Commit target, e.g. "main". */
-  branch: string;
-  appId: string;
-  installationId: string;
-}
-
 /** Magic-link sender identity for Cloudflare Email Sending. */
 export interface SenderConfig {
   from: string;
@@ -256,67 +179,73 @@ export interface AssetConfig {
   transformations?: boolean;
 }
 
-/** The single seam the engine consumes. A site implements this at `src/lib/cairn.config.ts`. */
+/**
+ * The site's one renderer (design decision 4): the editor preview and every public page call it.
+ *  Entry-aware so a custom renderer can vary output by concept or frontmatter; the default reads only
+ *  `body` plus the resolvers. `resolve` rewrites cairn: links to live permalinks (the build passes a
+ *  site-resolver-backed resolver, the preview a manifest-backed one); `resolveMedia` resolves media:
+ *  references the same way. `concept` and `frontmatter` carry the entry's context for an entry render
+ *  and are absent for the standalone component-insert preview.
+ */
+export type SiteRender = (input: {
+  body: string;
+  concept?: string;
+  frontmatter?: Record<string, unknown>;
+  resolve?: LinkResolve;
+  resolveMedia?: import('../render/resolve-media.js').MediaResolve;
+}) => Promise<string>;
+
+/**
+ * The single seam the engine consumes. A site implements this at `src/lib/cairn.config.ts`, in six
+ * subsystem groups (spec §8): the content concepts, the commit backend, the magic-link sender, the
+ * render subsystem, the optional media stack, and the admin-experience knobs. The internal manifest
+ * and dictionary paths are not here; `composeRuntime` defaults them by convention.
+ */
 export interface CairnAdapter {
-  siteName: string;
-  /**
-   * Which content concepts this site enables. A future `fragments?` key attaches here with
-   * no reshape of the contract (seam 1). A site never has two of the same concept.
-   */
-  content: {
-    posts?: ConceptConfig;
-    pages?: ConceptConfig;
+  /** The site's concepts, keyed by id. Posts and pages are the documented defaults; a site may add more. */
+  content: Record<string, ConceptConfig>;
+  /** The commit backend provider, from `githubApp({ ... })` (the GitHub App today). */
+  backend: BackendProvider;
+  /** The magic-link sender. */
+  email: SenderConfig;
+  /** The render subsystem: the one renderer, its directive vocabulary, and its icons. */
+  rendering: {
+    /**
+     * The one renderer the editor preview and every public page call (design decision 4). `resolve`
+     *  rewrites cairn: links to live permalinks; the build passes a site-resolver-backed one, the
+     *  preview a manifest one. `resolveMedia` resolves media: references the same way.
+     */
+    render: SiteRender;
+    /** Directive component registry; the renderer and the insert palette derive from it (seam 3). */
+    components?: ComponentRegistry;
+    /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
+    icons?: IconSet;
+    /**
+     * The live Svelte components for hydrated directives, keyed by directive name (phase 4b islands).
+     *  Every component whose {@link ComponentDef.hydrate} is set needs an entry here, and every entry
+     *  needs a matching `hydrate` component; `defineAdapter` checks both. Absent leaves the site
+     *  static, and the island client runtime is never imported.
+     */
+    islands?: IslandRegistry;
+  };
+  /** R2-backed media (seam 4): the bucket binding and image variants. Absent leaves media off. */
+  media?: AssetConfig;
+  /** Admin-experience knobs: the preview frame, the nav menu, and the editor support contact. */
+  editor?: {
+    /**
+     * The live site's content styling for the preview frame. The admin's chrome isolation keeps
+     *  the site's CSS out of the admin document, so the preview frame links these instead.
+     */
+    preview?: PreviewConfig;
+    /** Which git-committed YAML menu the nav editor manages. */
+    nav?: NavMenuConfig;
+    /**
+     * Optional contact a stuck editor is pointed to from the in-admin help (an email address, a URL,
+     *  or a name and instruction). The help renders the hand-off only when this is set. Plain string,
+     *  passed through verbatim.
+     */
+    supportContact?: string;
   };
-  backend: BackendConfig;
-  sender: SenderConfig;
-  /**
-   * Optional contact a stuck editor is pointed to from the in-admin help (an email address, a URL,
-   *  or a name and instruction). The help renders the hand-off only when this is set. Plain string,
-   *  passed through verbatim.
-   */
-  supportContact?: string;
-  /**
-   * The site's one renderer: the editor preview and every public page call it (design decision 4).
-   *  `resolve` rewrites cairn: links to live permalinks; the build passes a site-resolver-backed
-   *  one, the preview a manifest one. The trailing `resolveMedia` is additive and optional: the build
-   *  passes a site-resolver-backed media resolver, the preview a manifest-backed one.
-   */
-  render(
-    md: string,
-    opts?: {
-      stagger?: boolean;
-      resolve?: LinkResolve;
-      resolveMedia?: import('../render/resolve-media.js').MediaResolve;
-    },
-  ): string | Promise<string>;
-  /**
-   * Repo-relative path to the committed content manifest. Defaults to src/content/.cairn/index.json
-   *  in composeRuntime. It sits outside any concept directory, so content enumeration never globs it.
-   */
-  manifestPath?: string;
-  /**
-   * Repo-relative path to the committed media manifest. Defaults to src/content/.cairn/media.json,
-   *  applied in composeRuntime. Sits outside any concept directory, like the content manifest.
-   */
-  mediaManifestPath?: string;
-  /**
-   * Repo-relative path to the committed personal dictionary file. Defaults to
-   *  src/content/.cairn/dictionary.txt, applied in composeRuntime: the same `.cairn/` content root the
-   *  manifests use, so the spec's `content/.cairn/dictionary.txt` resolves the same configurable way the
-   *  manifest paths do. One word per line, sorted, comment lines allowed (see site-dictionary.ts).
-   */
-  dictionaryPath?: string;
-  /** Directive component registry; the renderer and the future palette derive from it (seam 3). */
-  registry?: ComponentRegistry;
-  /** The site's glyph name to SVG path-data map, for the admin icon picker and the renderer. */
-  icons?: IconSet;
-  navMenu?: NavMenuConfig;
-  /**
-   * The live site's content styling for the preview frame. The admin's chrome isolation keeps
-   *  the site's CSS out of the admin document, so the preview frame links these instead.
-   */
-  preview?: PreviewConfig;
-  assets?: AssetConfig;
 }
 
 /**
@@ -351,7 +280,17 @@ export interface ConceptDescriptor {
   permalink: string;
   /** Filename date-prefix granularity for a dated concept; resolved by `normalizeConcepts`. */
   datePrefix: DatePrefix;
-  fields: FrontmatterField[];
+  /**
+   * The concept's fields in normalized form: each descriptor with its record key re-attached as
+   *  `name`, derived by `normalizeConcepts` from the concept's `fieldset` record. Every consumer
+   *  (the editor form, the form decoder, the media extractor) iterates this array and reads `name`.
+   */
+  fields: NamedField[];
+  /**
+   * The concept's source fieldset, carried through so `editLoad` can resolve a create-form's
+   *  initial values (a `default: 'today'` date) against a request-time clock via `initialValues`.
+   */
+  schema: Fieldset;
   /**
    * Frontmatter keys the index copies onto each summary's `fields` record. `normalizeConcepts`
    *  resolves it to `[]` when a concept omits `summaryFields`.
@@ -412,23 +351,17 @@ export interface CairnExtension {
 export interface CairnRuntime {
   siteName: string;
   concepts: ConceptDescriptor[];
-  backend: BackendConfig;
+  /** The commit backend provider, carried through from the adapter by `composeRuntime`. */
+  backend: BackendProvider;
   sender: SenderConfig;
   /** The support contact passed through from the adapter; the in-admin help reads it. Optional. */
   supportContact?: string;
   /**
    * The site's one renderer: the editor preview and every public page call it (design decision 4).
-   *  The trailing `resolveMedia` is additive and optional: the build passes a site-resolver-backed
-   *  media resolver, the preview a manifest-backed one.
+   *  The build passes a site-resolver-backed `resolve`/`resolveMedia` pair, the preview manifest-backed
+   *  ones.
    */
-  render(
-    md: string,
-    opts?: {
-      stagger?: boolean;
-      resolve?: LinkResolve;
-      resolveMedia?: import('../render/resolve-media.js').MediaResolve;
-    },
-  ): string | Promise<string>;
+  render: SiteRender;
   manifestPath: string;
   /** The repo-relative path to the committed media manifest, defaulted in composeRuntime. */
   mediaManifestPath: string;

package/src/lib/delivery/data.ts

@@ -3,8 +3,8 @@
 // the graph. The full ./delivery barrel re-exports this and adds the route loaders.
 export { createContentIndex, fromGlob } from './content-index.js';
 export type { RawFile, ContentSummary, ContentEntry, ContentIndex, ContentProblem } from './content-index.js';
-export { createSiteResolver, buildLinkResolver } from './site-resolver.js';
-export type { SiteResolver, ConceptIndex } from './site-resolver.js';
+export { createSiteResolver, buildLinkResolver, resolveReferences } from './site-resolver.js';
+export type { SiteResolver, ConceptIndex, ResolvedReference } from './site-resolver.js';
 export { createSiteIndexes } from './site-indexes.js';
 export type { SiteIndexes, SiteGlobs } from './site-indexes.js';
 export { siteDescriptors } from './site-descriptors.js';

package/src/lib/delivery/public-routes.ts

@@ -10,14 +10,15 @@ import { buildSeoMeta } from './seo.js';
 import type { SeoMeta } from './seo.js';
 import { readSeoFields, resolveImageUrl } from './seo-fields.js';
 import { buildLinkResolver } from './site-resolver.js';
-import type { LinkResolve } from '../content/links.js';
+import type { SiteRender } from '../content/types.js';
 import type { MediaResolve } from '../render/resolve-media.js';
 import { parseMediaToken } from '../media/reference.js';
+import { log } from '../log/index.js';
 
 /** Injected dependencies for the public loaders. */
 export interface PublicRoutesDeps {
   site: SiteResolver;
-  render: (md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }) => string | Promise<string>;
+  render: SiteRender;
   origin: string;
   /** Site name for og:site_name and the SEO head. */
   siteName: string;
@@ -36,6 +37,14 @@ export interface PublicRoutesDeps {
    *  media is off and no `heroImage` projection is derived.
    */
   resolveMedia?: MediaResolve;
+  /**
+   * Whether the site configured media on, read from `runtime.resolvedAssets.enabled`. It exists only
+   *  to diagnose a forgotten wire-point: media on but no `resolveMedia` reached this factory, which
+   *  renders public hero and body images as bare `media:` tokens. When true and `resolveMedia` is
+   *  absent, the factory emits `media.resolver_absent` once at construction. It does not change
+   *  resolution; `resolveMedia` alone still gates the hero projection.
+   */
+  assetsEnabled?: boolean;
 }
 
 /** The archive and tag list data: summaries the template renders. */
@@ -74,7 +83,16 @@ export interface EntryData {
 
 /** Build the public loaders for a site's unified index. */
 export function createPublicRoutes(deps: PublicRoutesDeps) {
-  const { site, render, origin, siteName, description, feeds, defaultImage, resolveMedia } = deps;
+  const { site, render, origin, siteName, description, feeds, defaultImage, resolveMedia, assetsEnabled } = deps;
+
+  // Diagnose a forgotten wire-point: media is configured on but no resolver reached this factory, so
+  // every public hero and body `media:` token renders bare (the ecxc 0.57.0 finding). The condition
+  // is a property of the wiring, not of any one load, so it is checked once here at construction
+  // rather than per entryLoad or per image, which keeps the warning loud-once and out of the
+  // prerender hot path. Resolution is unchanged; resolveMedia alone still gates the hero projection.
+  if (assetsEnabled && !resolveMedia) {
+    log.warn('media.resolver_absent', { enabled: true });
+  }
 
   /**
    * Derive the hero projection from an entry's frontmatter, without mutating it (locked decision 5).
@@ -145,7 +163,21 @@ export function createPublicRoutes(deps: PublicRoutesDeps) {
       ...(fields.author ? { author: fields.author } : {}),
       ...(entry.date ? { feeds } : {}),
     });
-    return { concept: entry.concept, entry, html: await render(entry.body, { stagger: true, resolve: buildLinkResolver(site) }), canonicalUrl, seo, newer, older, ...(heroImage ? { heroImage } : {}) };
+    return {
+      concept: entry.concept,
+      entry,
+      html: await render({
+        body: entry.body,
+        concept: entry.concept,
+        frontmatter: entry.frontmatter,
+        resolve: buildLinkResolver(site),
+      }),
+      canonicalUrl,
+      seo,
+      newer,
+      older,
+      ...(heroImage ? { heroImage } : {}),
+    };
   }
 
   /** The chronological archive for one concept: every non-draft summary, newest-first. */