@glw907/cairn-cms 0.62.2 → 0.76.0

package/src/lib/sveltekit/guard.ts

@@ -41,6 +41,21 @@ export function createAuthGuard() {
   return async function handle({ event, resolve }: HandleInput): Promise<Response> {
     const { pathname } = event.url;
 
+    // Fail closed if the dev-backend flag is set in a deployed runtime. Read both env sources: a
+    // Cloudflare Worker var lands on platform.env, an adapter-node OS var on process.env. A correct
+    // production build already eliminated the dev backend (the consumer gates it on the build-foldable
+    // `dev`), so a set flag signals a polluted environment; refuse loudly.
+    const platformFlag = event.platform?.env?.CAIRN_DEV_BACKEND;
+    const processFlag =
+      typeof process !== 'undefined' ? process.env?.CAIRN_DEV_BACKEND : undefined;
+    if (platformFlag === '1' || platformFlag === true || processFlag === '1') {
+      log.error('guard.rejected', { reason: 'dev_backend_in_prod', path: pathname });
+      return new Response(
+        'cairn: the dev backend flag is set in a deployed environment. Unset CAIRN_DEV_BACKEND.',
+        { status: 503 },
+      );
+    }
+
     // Rule 2 - non-admin: restore the framework's strict Origin check the consumer disabled when
     // they set checkOrigin: false to hand cairn the admin CSRF authority.
     if (!isAdminPath(pathname)) {

package/src/lib/sveltekit/health.ts

@@ -2,8 +2,9 @@
 // PKCS#1-to-PKCS#8 conversion is caught early (spec §7.8). The payload is pass/fail and a
 // coarse detail only; it never carries the key or a token.
 import { signingSelfTest } from '../github/signing.js';
+import { isGithubApp } from '../github/backend.js';
 import type { CairnRuntime } from '../content/types.js';
-import type { GithubKeyEnv } from '../github/credentials.js';
+import type { BackendEnv } from '../github/credentials.js';
 
 /** The `/admin/healthz` payload. */
 export interface HealthData {
@@ -11,14 +12,20 @@ export interface HealthData {
   checks: { githubAppSigning: { ok: boolean; detail?: string } };
 }
 
-/** Run the signing self-test against the configured App id and the Worker's key secret. */
+/**
+ * Run the signing self-test against the configured App id and the Worker's key secret. The self-test
+ * is GitHub-specific, so it narrows the provider on `kind === 'github-app'` for the App id; a
+ * non-GitHub backend skips the signing check.
+ */
 export async function healthLoad(
-  event: { platform?: { env?: GithubKeyEnv } },
+  event: { platform?: { env?: BackendEnv } },
   runtime: CairnRuntime,
 ): Promise<HealthData> {
   const key = event.platform?.env?.GITHUB_APP_PRIVATE_KEY_B64;
-  const githubAppSigning = key
-    ? await signingSelfTest(runtime.backend.appId, key)
-    : { ok: false, detail: 'GITHUB_APP_PRIVATE_KEY_B64 is not configured' };
+  const provider = runtime.backend;
+  const githubAppSigning =
+    isGithubApp(provider) && key
+      ? await signingSelfTest(provider.appId, key)
+      : { ok: false, detail: 'GITHUB_APP_PRIVATE_KEY_B64 is not configured' };
   return { ok: githubAppSigning.ok, checks: { githubAppSigning } };
 }

package/src/lib/sveltekit/index.ts

@@ -35,7 +35,7 @@ export { parseAdminPath, type AdminView } from './admin-dispatch.js';
 export { createCairnAdmin, type CairnAdminDeps, type AdminData } from './cairn-admin.js';
 export { healthLoad, type HealthData } from './health.js';
 export type { RequestContext, CookieJar, HandleInput } from './types.js';
-// Re-exported here, not from root, so the public ContentRoutesDeps consumer can name it.
-export type { GithubKeyEnv } from '../github/credentials.js';
+// Re-exported here, not from root, so the consumer's app.d.ts Platform block can name it.
+export type { BackendEnv } from '../github/credentials.js';
 // Re-exported here, not just from root, so the app.d.ts Platform block can name it.
 export type { AuthEnv } from '../auth/types.js';

package/src/lib/sveltekit/nav-routes.ts

@@ -1,15 +1,13 @@
 // The admin nav-editing routes: the load and save a site's /admin/nav shim calls. A factory closes
-// over the composed runtime and the GitHub token mint, mirroring createContentRoutes, so the read
-// and commit paths are unit-testable against a fetch double with an injected token.
+// over the composed runtime, mirroring createContentRoutes, so the read and commit paths are
+// unit-testable against a fetch double behind an injected Backend.
 import { redirect, error } from '@sveltejs/kit';
-import { appCredentials, type GithubKeyEnv } from '../github/credentials.js';
-import { cachedInstallationToken } from '../github/signing.js';
-import { listMarkdown, readRaw, commitFile } from '../github/repo.js';
 import { isConflict } from '../github/types.js';
 import { log } from '../log/index.js';
 import { parseSiteConfig, extractMenu, validateNavTree, setMenu, type NavNode } from '../nav/site-config.js';
 import { requireSession } from './guard.js';
 import type { CairnRuntime } from '../content/types.js';
+import type { Backend } from '../github/backend.js';
 import type { ContentEvent } from './content-routes.js';
 
 /** One page option for the URL picker datalist. */
@@ -27,29 +25,35 @@ export interface NavLoadData {
   error: string | null;
 }
 
-/** Injectable dependencies; tests stub the token mint to avoid signing a real key. */
+/** Injectable dependencies; a test injects a live `Backend` so the read and commit paths run with no real token mint. */
 export interface NavRoutesDeps {
   /**
-   * Mint a GitHub App installation token from the Worker env. Defaults to the real signer.
-   *  A bare string works too; the routes await whatever comes back.
+   * Override the resolved content backend. A test injects a live `Backend` (a `makeGithubBackend`
+   *  over a fetch double) so the read and commit paths run with no real token mint. When set it
+   *  replaces the per-handler `locals.backend ?? runtime.backend.connect(env)` resolve.
    */
-  mintToken?: (env: GithubKeyEnv) => string | Promise<string>;
+  backend?: Backend;
 }
 
 /**
  *
  */
 export function createNavRoutes(runtime: CairnRuntime, deps: NavRoutesDeps = {}) {
-  const mintToken =
-    deps.mintToken ?? ((env: GithubKeyEnv) => cachedInstallationToken(appCredentials(runtime.backend, env)));
+  /**
+   * Resolve the live content backend for one request: the test seam, then the dev double's
+   *  `event.locals.backend`, then the production `runtime.backend.connect(env)`.
+   */
+  function resolveBackend(event: ContentEvent): Backend {
+    return deps.backend ?? event.locals.backend ?? runtime.backend.connect(event.platform?.env ?? {});
+  }
 
   /** List page-like concepts (routable, not dated) for the URL picker. Best-effort per concept. */
-  async function pageOptions(token: string): Promise<NavPageOption[]> {
+  async function pageOptions(backend: Backend): Promise<NavPageOption[]> {
     const pageConcepts = runtime.concepts.filter((c) => c.routing.routable && !c.routing.dated);
     const lists = await Promise.all(
       pageConcepts.map(async (c) => {
         try {
-          const files = await listMarkdown(runtime.backend, c.dir, token);
+          const files = await backend.readEntries(c.dir, backend.defaultBranch);
           return files.map((f): NavPageOption => ({ label: f.id, url: `/${f.id}` }));
         } catch {
           return [];
@@ -67,17 +71,12 @@ export function createNavRoutes(runtime: CairnRuntime, deps: NavRoutesDeps = {})
     const maxDepth = config.maxDepth ?? 2;
     const menu = { name: config.menuName, label: config.label, maxDepth };
 
-    let token: string;
-    try {
-      token = await mintToken(event.platform?.env ?? {});
-    } catch {
-      return { menu, tree: [], pages: [], saved: false, error: 'Could not authenticate with GitHub.' };
-    }
+    const backend = resolveBackend(event);
 
     let tree: NavNode[] = [];
     let raw: string | null = null;
     try {
-      raw = await readRaw(runtime.backend, config.configPath, token);
+      raw = await backend.readFile(config.configPath, backend.defaultBranch);
     } catch {
       // An unreadable config degrades to an empty tree; the first save writes a clean menu.
       raw = null;
@@ -99,7 +98,7 @@ export function createNavRoutes(runtime: CairnRuntime, deps: NavRoutesDeps = {})
     return {
       menu,
       tree,
-      pages: await pageOptions(token),
+      pages: await pageOptions(backend),
       saved: event.url.searchParams.get('saved') === '1',
       error: event.url.searchParams.get('error'),
     };
@@ -121,18 +120,23 @@ export function createNavRoutes(runtime: CairnRuntime, deps: NavRoutesDeps = {})
       throw redirect(303, `/admin/nav?error=${encodeURIComponent(message)}`);
     }
 
-    const token = await mintToken(event.platform?.env ?? {});
-    const raw = await readRaw(runtime.backend, config.configPath, token);
+    const backend = resolveBackend(event);
+    // Read the head BEFORE the content, so this expectedHead is at-or-before the bytes the commit
+    // merges. The nav write lands on the default branch and triggers a deploy, so it is fail-closed:
+    // a concurrent commit to the config moves the head off this value and the commit throws a
+    // conflict, surfacing the reload-and-reapply prompt below rather than a silent last-writer-wins.
+    const head = await backend.branchHead(backend.defaultBranch);
+    const raw = await backend.readFile(config.configPath, backend.defaultBranch);
     if (raw === null) throw error(404, 'Site config not found');
 
     const commitFields = { concept: 'nav', id: 'site-config', editor: editor.email };
     try {
-      await commitFile(
-        runtime.backend,
-        config.configPath,
-        setMenu(raw, config.menuName, tree),
-        { message: `Update ${config.label.toLowerCase()}`, author: { name: editor.displayName, email: editor.email } },
-        token,
+      await backend.commit(
+        backend.defaultBranch,
+        [{ path: config.configPath, content: setMenu(raw, config.menuName, tree) }],
+        { name: editor.displayName, email: editor.email },
+        `Update ${config.label.toLowerCase()}`,
+        head ?? undefined,
       );
       log.info('commit.succeeded', commitFields);
     } catch (err) {

package/src/lib/sveltekit/types.ts

@@ -1,6 +1,7 @@
 // Structural subsets of SvelteKit's RequestEvent. A site passes its real event, which has
 // these and more, so the engine never imports a site's generated App.* ambient types.
 import type { AuthEnv, Editor } from '../auth/types.js';
+import type { Backend } from '../github/backend.js';
 
 export interface CookieSetOptions {
   path: string;
@@ -31,7 +32,10 @@ export interface PlatformContext<Env> {
 export interface EventBase<Env> {
   url: URL;
   request: Request;
-  locals: { editor?: Editor | null };
+  // `backend` is the per-request content store the dev-backend handle injects; the engine resolves
+  // it ahead of the real provider, so typing it here makes the seam a checked contract rather than a
+  // cast. A production request leaves it absent and the real `githubApp` provider connects.
+  locals: { editor?: Editor | null; backend?: Backend };
   platform?: PlatformContext<Env>;
 }
 

package/src/lib/vite/index.ts

@@ -53,11 +53,17 @@ function virtualSource(opts: CairnManifestOptions, mode: 'verify' | 'write'): st
     .join('\n');
   // In write mode the committed file may not exist yet, so do not import it.
   const committedImport = mode === 'verify' ? `import committed from ${JSON.stringify(manifestPath + '?raw')};` : '';
+  // In verify mode, run verifyReferences after verifyManifest, inside the generated source where the
+  // built manifest is in scope. References have no prerender backstop, so this build gate is their only
+  // integrity authority; it cannot move to the verifyManifestFromVite TS call site, where `built` does
+  // not exist (it lives only in this evaluated string).
   const resultExpr =
-    mode === 'write' ? 'serializeManifest(built)' : '(verifyManifest(built, committed), "ok")';
+    mode === 'write'
+      ? 'serializeManifest(built)'
+      : '(verifyManifest(built, committed), verifyReferences(built), "ok")';
   return `
 import { buildSiteManifest } from '@glw907/cairn-cms/delivery/data';
-import { serializeManifest, verifyManifest } from '@glw907/cairn-cms';
+import { serializeManifest, verifyManifest, verifyReferences } from '@glw907/cairn-cms';
 import { cairn, siteConfig } from ${JSON.stringify(opts.configModule)};
 ${committedImport}
 const globs = {
@@ -242,11 +248,11 @@ export interface AdapterFacts {
   owner?: string;
   /** `cairn.backend.repo`. */
   repo?: string;
-  /** `cairn.sender.from`. */
+  /** `cairn.email.from`. */
   from?: string;
   /**
-   * `cairn.assets.bucketBinding`, the media R2 binding name; undefined when the adapter declares no
-   *  assets. The doctor's conditional media-bucket check reads it.
+   * `cairn.media.bucketBinding`, the media R2 binding name; undefined when the adapter declares no
+   *  media. The doctor's conditional media-bucket check reads it.
    */
   mediaBucketBinding?: string;
 }
@@ -261,13 +267,16 @@ function adapterFactsSource(opts: CairnManifestOptions): string {
   return `
 import { cairn } from ${JSON.stringify(opts.configModule)};
 const backend = cairn?.backend ?? {};
-const sender = cairn?.sender ?? {};
-const assets = cairn?.assets ?? {};
+const email = cairn?.email ?? {};
+const media = cairn?.media ?? {};
 const facts = {};
-if (typeof backend.owner === 'string') facts.owner = backend.owner;
-if (typeof backend.repo === 'string') facts.repo = backend.repo;
-if (typeof sender.from === 'string') facts.from = sender.from;
-if (typeof assets.bucketBinding === 'string') facts.mediaBucketBinding = assets.bucketBinding;
+// The owner/repo identity is GitHub-specific, so it is read only off the github-app provider.
+if (backend.kind === 'github-app') {
+  if (typeof backend.owner === 'string') facts.owner = backend.owner;
+  if (typeof backend.repo === 'string') facts.repo = backend.repo;
+}
+if (typeof email.from === 'string') facts.from = email.from;
+if (typeof media.bucketBinding === 'string') facts.mediaBucketBinding = media.bucketBinding;
 export const result = JSON.stringify(facts);
 `;
 }

package/dist/content/schema.d.ts

@@ -1,87 +0,0 @@
-import type { FrontmatterField, ImageValue, ValidationResult } from './types.js';
-/** 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>;
-    }>;
-};
-/**
- * Map one field descriptor to the TS type of its normalized value. text, textarea, and date
- *  normalize to a string; a closed-vocabulary `tags` field to the option-union array; an `image`
- *  field to its nested object.
- */
-type FieldValue<K extends FrontmatterField> = K extends {
-    type: 'boolean';
-} ? boolean : K extends {
-    type: 'image';
-} ? ImageValue : K extends {
-    type: 'tags';
-    options: readonly (infer O extends string)[];
-} ? O[] : K extends {
-    type: 'tags' | 'freetags';
-} ? string[] : string;
-/** Flatten an intersection into a single readable object type. */
-type Prettify<T> = {
-    [K in keyof T]: T[K];
-} & {};
-/**
- * The normalized frontmatter type inferred from a field tuple. A field declared
- *  `required: true` is a required key; every other field is optional.
- */
-export type InferFields<F extends readonly FrontmatterField[]> = Prettify<{
-    [K in F[number] as K extends {
-        required: true;
-    } ? K['name'] : never]: FieldValue<K>;
-} & {
-    [K in F[number] as K extends {
-        required: true;
-    } ? never : K['name']]?: FieldValue<K>;
-}>;
-/**
- * A concept's schema: the plain-data field projection, the generated validator, and the
- *  Standard Schema conformance property.
- */
-export interface ConceptSchema<F extends readonly FrontmatterField[] = readonly FrontmatterField[]> {
-    /** The declared fields as plain serializable data, for the editor form. */
-    readonly fields: FrontmatterField[];
-    /** Validate raw frontmatter, returning field-keyed errors or the normalized data. */
-    validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
-    /** Standard Schema v1 conformance, for ecosystem interop. A thin adapter over `validate`. */
-    readonly '~standard': StandardSchemaV1<StandardInput, InferFields<F>>['~standard'];
-}
-/** Extract the inferred frontmatter type from a `ConceptSchema`. */
-export type Infer<S> = S extends ConceptSchema<infer F> ? InferFields<F> : never;
-/**
- * Options for `defineFields`. `refine` runs after the per-field rules pass, for cross-field and
- *  body-dependent checks. It is validation-only: it returns field-keyed errors to merge, or
- *  nothing, and never transforms the data.
- */
-export interface DefineFieldsOptions<F extends readonly FrontmatterField[]> {
-    refine?: (data: InferFields<F>, body: string) => Record<string, string> | undefined;
-}
-/** Declare a concept's fields once. Returns the schema's faces derived from that one declaration. */
-export declare function defineFields<const F extends readonly FrontmatterField[]>(fields: F, options?: DefineFieldsOptions<F>): ConceptSchema<F>;
-export {};

package/dist/content/schema.js

@@ -1,89 +0,0 @@
-import { validateFields } from './validate.js';
-// Enforce the declarative per-field rules on an already-coerced value. Rules run only on a
-// present, non-empty string value, so an absent optional field is never flagged. The first
-// failing rule per field wins, so the author sees one clear message at a time.
-function applyRules(field, value, errors, patterns) {
-    if (typeof value !== 'string' || value === '')
-        return;
-    if (field.type === 'text' || field.type === 'textarea') {
-        if (field.min != null && value.length < field.min)
-            errors[field.name] = `${field.label} must be at least ${field.min} characters`;
-        else if (field.max != null && value.length > field.max)
-            errors[field.name] = `${field.label} must be at most ${field.max} characters`;
-        else if (field.length != null && value.length !== field.length)
-            errors[field.name] = `${field.label} must be exactly ${field.length} characters`;
-        else if (field.pattern != null) {
-            const re = patterns.get(field.name);
-            if (re && !re.test(value))
-                errors[field.name] = `${field.label} is not in the expected format`;
-        }
-    }
-    else if (field.type === 'date') {
-        if (field.min != null && value < field.min)
-            errors[field.name] = `${field.label} must be on or after ${field.min}`;
-        else if (field.max != null && value > field.max)
-            errors[field.name] = `${field.label} must be on or before ${field.max}`;
-    }
-}
-// Compile each declared text/textarea pattern once, so a malformed pattern fails loudly at
-// declaration (a site config error) instead of throwing from inside validate() on every save.
-function compilePatterns(fields) {
-    const compiled = new Map();
-    for (const field of fields) {
-        if ((field.type === 'text' || field.type === 'textarea') && field.pattern != null) {
-            try {
-                compiled.set(field.name, new RegExp(field.pattern));
-            }
-            catch (cause) {
-                throw new Error(`cairn: field "${field.name}" has an invalid pattern: ${field.pattern}`, { cause });
-            }
-        }
-    }
-    return compiled;
-}
-// True when an image field feeds the social card: an explicit `seo: true`, or the back-compat
-// default that the field named `image` is the SEO image. The SEO unify (Task 4) reads this flag.
-function isSeoImage(field) {
-    return field.type === 'image' && (field.seo === true || (field.seo === undefined && field.name === 'image'));
-}
-// A concept declares at most one SEO image field, so the social card is unambiguous. More than one
-// is a site config error: a hero named `cover` plus an explicit `seo` on another, or two explicit
-// `seo` fields. Fail loudly at declaration rather than emit a silent or wrong og:image.
-function checkSeoImageFields(fields) {
-    const seo = fields.filter(isSeoImage);
-    if (seo.length > 1) {
-        const names = seo.map((field) => `"${field.name}"`).join(', ');
-        throw new Error(`cairn: a concept declares at most one SEO image field, but found ${seo.length} (${names}). ` +
-            'Set seo: false on all but one, or rename the extra image fields so only one feeds the social card.');
-    }
-}
-/** Declare a concept's fields once. Returns the schema's faces derived from that one declaration. */
-export function defineFields(fields, options = {}) {
-    const list = [...fields];
-    const patterns = compilePatterns(list);
-    checkSeoImageFields(list);
-    const validate = (frontmatter, body) => {
-        const base = validateFields(list, frontmatter);
-        if (!base.ok)
-            return base;
-        const errors = {};
-        for (const field of list)
-            applyRules(field, base.data[field.name], errors, patterns);
-        if (Object.keys(errors).length > 0)
-            return { ok: false, errors };
-        const refined = options.refine?.(base.data, body);
-        return refined && Object.keys(refined).length > 0 ? { ok: false, errors: refined } : base;
-    };
-    const standard = {
-        version: 1,
-        vendor: 'cairn',
-        validate: (value) => {
-            const { frontmatter = {}, body = '' } = (value ?? {});
-            const result = validate(frontmatter ?? {}, body ?? '');
-            return result.ok
-                ? { value: result.data }
-                : { issues: Object.entries(result.errors).map(([field, message]) => ({ message, path: [field] })) };
-        },
-    };
-    return { fields: list, validate, '~standard': standard };
-}

package/dist/content/validate.d.ts

@@ -1,17 +0,0 @@
-import type { FrontmatterField, ValidationResult } from './types.js';
-/**
- * Validate raw frontmatter against a field list. Required text and date fields must be
- * non-empty; required tag fields must be non-empty lists. A present boolean coerces to `true`
- * and an unchecked one is omitted; a present tag field coerces to a string array and an empty
- * one is omitted, so validated data carries no key for an absent tag field (`tags` or `freetags`).
- * The delivery read model
- * (`ContentSummary.tags`) fills that case with an empty array; the two layers differ on purpose.
- * An empty optional text or date field is omitted, so the normalized data
- * carries only meaningful values and committed frontmatter stays minimal. Returns the
- * normalized data, or field-keyed errors when any required field is empty.
- *
- * Frontmatter may arrive from the edit form (all string values) or from `parseMarkdown`,
- * where gray-matter turns an unquoted YAML date into a JS `Date`. The `date` case coerces a
- * `Date` to `YYYY-MM-DD` so a valid parsed date is not mistaken for an empty one.
- */
-export declare function validateFields(fields: FrontmatterField[], frontmatter: Record<string, unknown>): ValidationResult;

package/dist/content/validate.js

@@ -1,93 +0,0 @@
-import { dateInputValue, isCalendarDate } from './frontmatter.js';
-/**
- * Validate raw frontmatter against a field list. Required text and date fields must be
- * non-empty; required tag fields must be non-empty lists. A present boolean coerces to `true`
- * and an unchecked one is omitted; a present tag field coerces to a string array and an empty
- * one is omitted, so validated data carries no key for an absent tag field (`tags` or `freetags`).
- * The delivery read model
- * (`ContentSummary.tags`) fills that case with an empty array; the two layers differ on purpose.
- * An empty optional text or date field is omitted, so the normalized data
- * carries only meaningful values and committed frontmatter stays minimal. Returns the
- * normalized data, or field-keyed errors when any required field is empty.
- *
- * Frontmatter may arrive from the edit form (all string values) or from `parseMarkdown`,
- * where gray-matter turns an unquoted YAML date into a JS `Date`. The `date` case coerces a
- * `Date` to `YYYY-MM-DD` so a valid parsed date is not mistaken for an empty one.
- */
-export function validateFields(fields, frontmatter) {
-    const data = {};
-    const errors = {};
-    for (const field of fields) {
-        const value = frontmatter[field.name];
-        switch (field.type) {
-            case 'boolean':
-                // Absent or unchecked means false; omit it so a published file carries no draft: false noise.
-                if (value === true)
-                    data[field.name] = true;
-                break;
-            case 'tags':
-            case 'freetags': {
-                const list = Array.isArray(value) ? value.map(String) : [];
-                if (field.required && list.length === 0)
-                    errors[field.name] = `${field.label} is required`;
-                else if (field.type === 'tags') {
-                    const unknown = list.find((tag) => !field.options.includes(tag));
-                    if (unknown !== undefined)
-                        errors[field.name] = `${field.label} contains an unknown value: ${unknown}`;
-                }
-                if (list.length > 0)
-                    data[field.name] = list;
-                break;
-            }
-            case 'image': {
-                // A hero is the nested object { src, alt, caption }. Normalize a well-formed value (default
-                // a missing alt to empty, since alt is debt and never a save block), and drop the key when
-                // src is empty or absent. A malformed value (a string, or an object without a string src)
-                // drops the key rather than throwing, so a hand-edit never breaks a save.
-                let src = '';
-                if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
-                    const obj = value;
-                    src = typeof obj.src === 'string' ? obj.src.trim() : '';
-                    if (src !== '') {
-                        const normalized = {
-                            src,
-                            alt: typeof obj.alt === 'string' ? obj.alt : '',
-                        };
-                        const caption = typeof obj.caption === 'string' ? obj.caption.trim() : '';
-                        if (caption !== '')
-                            normalized.caption = caption;
-                        // An explicit decorative choice carries through; it is never required and never a save
-                        // block. A missing or non-boolean value drops the key, like a blank caption.
-                        if (obj.decorative === true)
-                            normalized.decorative = true;
-                        data[field.name] = normalized;
-                    }
-                }
-                // A required image needs a src (the presence check), like the other arms; alt is never
-                // required, since alt is debt. The inferred type makes a required image non-optional, so the
-                // validator must enforce it or a save could omit it against the type.
-                if (field.required && src === '')
-                    errors[field.name] = `${field.label} is required`;
-                break;
-            }
-            case 'date': {
-                const text = value instanceof Date ? dateInputValue(value) : typeof value === 'string' ? value.trim() : '';
-                if (field.required && text === '')
-                    errors[field.name] = `${field.label} is required`;
-                else if (text !== '' && !isCalendarDate(text))
-                    errors[field.name] = `${field.label} must be a valid date (YYYY-MM-DD)`;
-                if (text !== '')
-                    data[field.name] = text;
-                break;
-            }
-            default: {
-                const text = typeof value === 'string' ? value.trim() : '';
-                if (field.required && text === '')
-                    errors[field.name] = `${field.label} is required`;
-                if (text !== '')
-                    data[field.name] = text;
-            }
-        }
-    }
-    return Object.keys(errors).length > 0 ? { ok: false, errors } : { ok: true, data };
-}