@glw907/cairn-cms 0.68.0 → 0.76.0

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,7 +10,7 @@ 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';
@@ -18,7 +18,7 @@ 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;
@@ -163,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. */

package/src/lib/delivery/site-descriptors.ts

@@ -1,11 +1,16 @@
 // cairn-cms: the one-call descriptor helper. A delivery site needs the same per-concept descriptors
 // the admin runtime uses; this delegates to the shared resolveConcepts so the pairing is one path, not
-// tribal knowledge. The YAML URL policy stays the single source of truth.
+// tribal knowledge. Each concept declares its own routing and URL policy, the single source of truth.
 import { resolveConcepts } from '../content/concepts.js';
 import type { CairnAdapter, ConceptDescriptor } from '../content/types.js';
 import type { SiteConfig } from '../nav/site-config.js';
 
-/** Per-concept descriptors for a site, from its adapter content and its parsed site config. */
+/**
+ * Per-concept descriptors for a site, from its adapter content. The `siteConfig` parameter is retained
+ *  for API stability and the menus and site name it still carries; the URL policy now lives on each
+ *  concept, so it is not read here.
+ */
 export function siteDescriptors(adapter: CairnAdapter, siteConfig: SiteConfig): ConceptDescriptor[] {
-  return resolveConcepts(adapter.content, siteConfig);
+  void siteConfig;
+  return resolveConcepts(adapter.content);
 }

package/src/lib/delivery/site-indexes.ts

@@ -5,7 +5,7 @@
 // lower-level escape hatch. It imports only pure content and delivery code, so the delivery
 // bundle stays backend-free.
 import type { CairnAdapter, ConceptConfig } from '../content/types.js';
-import type { Infer } from '../content/schema.js';
+import type { InferFieldset } from '../content/fieldset.js';
 import type { SiteConfig } from '../nav/site-config.js';
 import { siteDescriptors } from './site-descriptors.js';
 import { createContentIndex, fromGlob } from './content-index.js';
@@ -24,7 +24,7 @@ export type SiteGlobs<A extends CairnAdapter> = {
  */
 export type SiteIndexes<A extends CairnAdapter> = {
   [K in keyof A['content']]: ContentIndex<
-    NonNullable<A['content'][K]> extends ConceptConfig<infer S> ? Infer<S> : Record<string, unknown>
+    NonNullable<A['content'][K]> extends ConceptConfig<infer S> ? InferFieldset<S> : Record<string, unknown>
   >;
 } & { readonly site: SiteResolver };
 

package/src/lib/delivery/site-resolver.ts

@@ -6,6 +6,7 @@
 import type { ConceptDescriptor } from '../content/types.js';
 import type { ContentEntry, ContentIndex, ContentSummary } from './content-index.js';
 import type { LinkResolve } from '../content/links.js';
+import { extractReferenceEdges, type ReferenceEdge } from '../content/references.js';
 
 /** One concept's descriptor paired with its built index. */
 export interface ConceptIndex {
@@ -93,6 +94,69 @@ export function createSiteResolver(concepts: ConceptIndex[], opts: { validate?:
   };
 }
 
+/**
+ * A reference edge resolved to its target's identity, for a public route to render a linked target.
+ *  It reuses the target entry's own summary fields rather than re-deriving them, so a linked author
+ *  card reads the same title and permalink the target's own page does. `summary` is the target's
+ *  excerpt when present.
+ */
+export interface ResolvedReference {
+  id: string;
+  concept: string;
+  title: string;
+  permalink: string;
+  summary?: string;
+}
+
+/** Project a resolved target entry into the identity a public route renders for a reference. */
+function projectReference(edge: ReferenceEdge, target: ContentSummary): ResolvedReference {
+  const resolved: ResolvedReference = {
+    id: edge.id,
+    concept: edge.concept,
+    title: target.title,
+    permalink: target.permalink,
+  };
+  if (target.excerpt) resolved.summary = target.excerpt;
+  return resolved;
+}
+
+/**
+ * Resolve a concept's `reference` and `array(reference)` frontmatter edges to their target identities,
+ * keyed by the field name, so a public route renders a reference as a link to its target's page. The
+ * resolution lives here because only the cross-concept resolver reaches a different concept's entries:
+ * a posts entry's `author` edge targets a pages entry, which the posts index alone cannot read. A
+ * single `reference` field resolves to one `ResolvedReference`, an `array(reference)` to a
+ * `ResolvedReference[]` in edge order. An id with no live target is dropped rather than thrown: the
+ * build's `verifyReferences` gate already fails a true dangling edge, so an unresolved id at request
+ * time is a mid-flight or draft target, not a hard error. Resolve per call, since the target entries
+ * exist only after every per-concept index is unioned into the resolver.
+ */
+export function resolveReferences(
+  site: SiteResolver,
+  descriptor: ConceptDescriptor,
+  frontmatter: Record<string, unknown>,
+): Record<string, ResolvedReference | ResolvedReference[]> {
+  const edges = extractReferenceEdges(frontmatter, descriptor.fields);
+  const resolved: Record<string, ResolvedReference | ResolvedReference[]> = {};
+  for (const field of descriptor.fields) {
+    const isSingle = field.type === 'reference';
+    const isArray = field.type === 'array' && field.item.type === 'reference';
+    if (!isSingle && !isArray) continue;
+    const fieldEdges = edges.filter((edge) => edge.field === field.name);
+    const hits: ResolvedReference[] = [];
+    for (const edge of fieldEdges) {
+      const target = site.concept(edge.concept)?.byId(edge.id);
+      if (target) hits.push(projectReference(edge, target));
+    }
+    if (isSingle) {
+      if (hits.length > 0) resolved[field.name] = hits[0];
+    } else {
+      resolved[field.name] = hits;
+    }
+  }
+  return resolved;
+}
+
 /**
  * A resolver backed by the site resolver, for the build. A miss throws, so a dangling cairn: token
  *  fails the prerender (the build backstop). The preview uses manifestLinkResolver, which marks.

package/src/lib/doctor/checks-local.ts

@@ -5,11 +5,8 @@ import { fail, pass, skip } from './types.js';
 import type { CheckResult, DoctorCheck, DoctorContext } from './types.js';
 import { readWranglerConfig } from './wrangler-config.js';
 import { requireOrigin } from '../env.js';
-import { parseSiteConfig, urlPolicyFrom } from '../nav/site-config.js';
+import { parseSiteConfig } from '../nav/site-config.js';
 import type { SiteConfig } from '../nav/site-config.js';
-import { normalizeConcepts } from '../content/concepts.js';
-import { defineFields } from '../content/schema.js';
-import type { ConceptConfig } from '../content/types.js';
 
 const NO_WRANGLER: CheckResult = skip('no wrangler.jsonc or wrangler.toml found');
 
@@ -156,16 +153,11 @@ export const configSiteConfig: DoctorCheck = {
 		const text = await readSiteConfigText(ctx);
 		if (text === null) return skip(`no site.config.yaml found (looked in ${SITE_CONFIG_PATHS.join(', ')})`);
 		try {
-			const policy = urlPolicyFrom(parseSiteConfig(text));
-			// Run the engine's own URL-policy validation by declaring a synthetic empty concept
-			// per policy key. Routing is concept-fixed in the engine (CONCEPT_ROUTING, never the
-			// adapter), so the dated rules apply faithfully here. What a CLI cannot check without
-			// evaluating the adapter is whether each policy key names a concept the site declares.
-			const synthetic = Object.fromEntries(
-				Object.keys(policy).map((id): [string, ConceptConfig] => [id, { dir: '', schema: defineFields([]) }])
-			);
-			normalizeConcepts(synthetic, policy);
-			return pass('parsed and URL policy validated (the adapter concept set is not checkable from the CLI)');
+			// Parse-only. parseSiteConfig validates the root shape and, since Contract v2, hard-errors on a
+			// stale per-concept `content:` block (URL policy moved onto defineConcept). The per-concept URL
+			// policy is now validated at the concept declaration, which a CLI cannot reach without the adapter.
+			parseSiteConfig(text);
+			return pass('parsed (per-concept URL policy lives on the adapter concepts, not checkable from the CLI)');
 		} catch (err) {
 			return fail(err instanceof Error ? err.message : String(err));
 		}