@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/shared/stories/pack/validateStoryPackDefinition.ts

@@ -0,0 +1,859 @@
+import { PragmaError } from "#error";
+import { MAX_SAMPLE_COUNT, MIN_SAMPLE_COUNT } from "../../parseSampleCount.js";
+import type {
+  StoryPackColumn,
+  StoryPackDefinition,
+  StoryPackDisclosure,
+  StoryPackExpand,
+  StoryPackExpandField,
+  StoryPackField,
+  StoryPackFilter,
+  StoryPackList,
+  StoryPackLookup,
+  StoryPackSample,
+  StoryPackSearch,
+  StoryPackSection,
+  StoryPackVerb,
+} from "./types.js";
+
+const NOUN_PATTERN = /^[a-z][a-z0-9-]*$/;
+const FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Object-prototype key names no pack identifier may take.
+ *
+ * Pack identifiers become plain-object keys at run time — SELECT
+ * variables become row keys, expand names become entity keys, and filter
+ * params become parameter keys — so `__proto__`/`constructor`/`prototype`
+ * are rejected at boot, before any row or params object could be built
+ * with a prototype-polluting key.
+ */
+const RESERVED_OBJECT_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/**
+ * Reject an identifier that names a reserved object-prototype key.
+ *
+ * Shared guard for every FIELD_PATTERN/FILTER_PARAM_PATTERN-shaped
+ * identifier (column fields, field/section/expand/select names, filter
+ * params and variables, search variables, disclosure levels).
+ *
+ * @throws PragmaError with code `CONFIG_ERROR` when the value is reserved.
+ */
+function rejectReservedObjectKey(
+  value: string,
+  where: string,
+  source: string,
+): void {
+  if (RESERVED_OBJECT_KEYS.has(value)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}" must not be the reserved object key "${value}".`,
+    );
+  }
+}
+/** A prefixed name (`ex:Recipe`) — prefix + local part, no path slashes. */
+const PREFIXED_NAME_PATTERN = /^[A-Za-z][\w-]*:[^/<>"\s]+$/;
+
+/** An absolute IRI that can be safely embedded as `<iri>` in SPARQL. */
+const EMBEDDABLE_IRI_PATTERN = /^[A-Za-z][\w+.-]*:\/\/[^<>"\s]+$/;
+
+/**
+ * Whether a resolved IRI matches the embeddable shape pack terms are held
+ * to (no whitespace or `<>"` characters, `scheme://` form).
+ *
+ * Shared with the lookup path so an IRI-addressed lookup applies the same
+ * strictness to resolved user queries as this validator applies to
+ * authored pack terms before either is embedded as `<iri>` in SPARQL.
+ */
+export function isEmbeddableIri(value: string): boolean {
+  return EMBEDDABLE_IRI_PATTERN.test(value);
+}
+
+/**
+ * A filter parameter name: a single lowercase word.
+ *
+ * Deliberately stricter than a noun (no hyphens): the name is used
+ * verbatim as the CLI flag, the Commander result key, and the MCP
+ * parameter key. A hyphenated name would register as `--meal-type` but
+ * be read back by Commander under the camelCased `mealType`, so the
+ * filter would silently never apply on the CLI while working on MCP.
+ * Restricting to one lowercase word keeps all three identical.
+ */
+const FILTER_PARAM_PATTERN = /^[a-z][a-z0-9]*$/;
+
+/**
+ * Parameter names taken by global flags or parameters the kernel appends
+ * to every read story — `condensed` is added to every MCP list tool,
+ * `detailed` to every lookup, `search` is the compiled free-text search
+ * parameter, and `detail` the disclosure level selector — so a filter may
+ * not reuse them.
+ */
+const RESERVED_FILTER_PARAMS = new Set([
+  "llm",
+  "format",
+  "verbose",
+  "detail",
+  "detailed",
+  "condensed",
+  "names",
+  "search",
+  "help",
+]);
+
+/**
+ * Names a disclosure level may not take. Levels derive parameters — the
+ * `--detail <level>` selector plus one boolean alias flag per non-base
+ * level — so a level must not collide with `detail` itself, the lookup's
+ * `names` positional, or kernel/global parameter names. `detailed` is
+ * deliberately absent: it is the expected name for a pack's legacy
+ * detailed level and derives the compatible `--detailed`/`detailed`
+ * alias.
+ */
+const RESERVED_LEVEL_NAMES = new Set([
+  "detail",
+  "names",
+  "condensed",
+  "search",
+  "llm",
+  "format",
+  "verbose",
+  "help",
+]);
+
+/**
+ * Validate one raw story-pack definition.
+ *
+ * Fails fast with `CONFIG_ERROR` naming the source and the offending
+ * field, mirroring how the `packages` config field is validated.
+ *
+ * @param raw - Parsed JSON value to validate.
+ * @param source - Where the definition came from, for error messages.
+ * @returns The validated definition.
+ * @throws PragmaError with code `CONFIG_ERROR` when the shape is invalid.
+ */
+export default function validateStoryPackDefinition(
+  raw: unknown,
+  source: string,
+): StoryPackDefinition {
+  const obj = requireObject(raw, "story", source);
+
+  const noun = requireString(obj.noun, "noun", source);
+  if (!NOUN_PATTERN.test(noun)) {
+    throw buildStoryConfigError(
+      source,
+      `"noun" must be kebab-case, got "${noun}".`,
+    );
+  }
+
+  const description =
+    obj.description === undefined
+      ? undefined
+      : requireString(obj.description, "description", source);
+  const toolDescription =
+    obj.toolDescription === undefined
+      ? undefined
+      : requireString(obj.toolDescription, "toolDescription", source);
+
+  const list = validateList(obj.list, source);
+  const verbs = validateVerbs(obj.verbs, source);
+  const lookup =
+    obj.lookup === undefined ? undefined : validateLookup(obj.lookup, source);
+
+  return {
+    noun,
+    ...(description !== undefined ? { description } : {}),
+    ...(toolDescription !== undefined ? { toolDescription } : {}),
+    list,
+    ...(verbs ? { verbs } : {}),
+    ...(lookup ? { lookup } : {}),
+  };
+}
+
+/**
+ * Verbs the compiler itself emits for a pack noun — an extra verb may not
+ * collide with them.
+ */
+const COMPILED_VERBS = new Set(["list", "lookup", "sample"]);
+
+function validateVerbs(
+  raw: unknown,
+  source: string,
+): readonly StoryPackVerb[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw buildStoryConfigError(source, '"verbs" must be a non-empty array.');
+  }
+  const seen = new Set<string>();
+  return raw.map((entry, index) => {
+    const where = `verbs[${index}]`;
+    const obj = requireObject(entry, where, source);
+    const verb = requireString(obj.verb, `${where}.verb`, source);
+    if (!NOUN_PATTERN.test(verb)) {
+      throw buildStoryConfigError(
+        source,
+        `"${where}.verb" must be kebab-case, got "${verb}".`,
+      );
+    }
+    if (COMPILED_VERBS.has(verb)) {
+      throw buildStoryConfigError(
+        source,
+        `"${where}.verb" "${verb}" collides with a compiled verb.`,
+      );
+    }
+    if (seen.has(verb)) {
+      throw buildStoryConfigError(source, `duplicate verb "${verb}".`);
+    }
+    seen.add(verb);
+    const description =
+      obj.description === undefined
+        ? undefined
+        : requireString(obj.description, `${where}.description`, source);
+    const toolDescription =
+      obj.toolDescription === undefined
+        ? undefined
+        : requireString(
+            obj.toolDescription,
+            `${where}.toolDescription`,
+            source,
+          );
+    return {
+      verb,
+      ...(description !== undefined ? { description } : {}),
+      ...(toolDescription !== undefined ? { toolDescription } : {}),
+      ...validateListShape(entry, where, source),
+    };
+  });
+}
+
+function validateList(
+  raw: unknown,
+  source: string,
+): StoryPackDefinition["list"] {
+  return validateListShape(raw, "list", source);
+}
+
+/**
+ * Validate a list-shaped story half: query, columns, filters, and search.
+ *
+ * Shared by `list` and (pack v1) extra list verbs, which compile through
+ * the same machinery. `where` names the field path for error messages.
+ */
+function validateListShape(
+  raw: unknown,
+  where: string,
+  source: string,
+): StoryPackList {
+  const obj = requireObject(raw, where, source);
+  const query = requireString(obj.query, `${where}.query`, source);
+  // Strip leading PREFIX declarations so the real query verb is checked —
+  // "PREFIX ex: <…> CONSTRUCT {…}" must fail here, not at first use.
+  const afterPrefixes = query.replace(
+    /^(\s*PREFIX\s+[A-Za-z][\w-]*:\s*<[^>]*>)+/i,
+    "",
+  );
+  if (!/^\s*SELECT\s/i.test(afterPrefixes)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.query" must be a SPARQL SELECT query.`,
+    );
+  }
+
+  if (!Array.isArray(obj.columns) || obj.columns.length === 0) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.columns" must be a non-empty array.`,
+    );
+  }
+  const columns = obj.columns.map((column, index) =>
+    validateColumn(column, `${where}.columns[${index}]`, source),
+  );
+  // Like filters and search below: a column naming a variable the query
+  // never binds is a typo that should fail at boot, not render an
+  // always-empty column at first use.
+  for (const column of columns) {
+    if (!referencesVariable(query, column.field)) {
+      throw buildStoryConfigError(
+        source,
+        `column field "?${column.field}" does not appear in "${where}.query".`,
+      );
+    }
+  }
+
+  const filters = validateFilterArray(obj.filters, where, source);
+  for (const filter of filters ?? []) {
+    if (!referencesVariable(query, filter.variable)) {
+      throw buildStoryConfigError(
+        source,
+        `filter variable "?${filter.variable}" does not appear in "${where}.query".`,
+      );
+    }
+  }
+
+  const search = validateSearch(obj.search, query, where, source);
+
+  return {
+    query,
+    columns,
+    ...(filters ? { filters } : {}),
+    ...(search ? { search } : {}),
+  };
+}
+
+/**
+ * Validate a list's free-text `search` declaration.
+ *
+ * Every searched variable must appear in the query — like filters, this
+ * fails a typo at boot instead of a search that silently never matches.
+ */
+function validateSearch(
+  raw: unknown,
+  query: string,
+  where: string,
+  source: string,
+): StoryPackSearch | undefined {
+  if (raw === undefined) return undefined;
+  const obj = requireObject(raw, `${where}.search`, source);
+  if (!Array.isArray(obj.variables) || obj.variables.length === 0) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.search.variables" must be a non-empty array.`,
+    );
+  }
+  const variables = obj.variables.map((value, index) => {
+    const variable = requireString(
+      value,
+      `${where}.search.variables[${index}]`,
+      source,
+    );
+    if (!FIELD_PATTERN.test(variable)) {
+      throw buildStoryConfigError(
+        source,
+        `"${where}.search.variables[${index}]" must name a SELECT variable.`,
+      );
+    }
+    rejectReservedObjectKey(
+      variable,
+      `${where}.search.variables[${index}]`,
+      source,
+    );
+    if (!referencesVariable(query, variable)) {
+      throw buildStoryConfigError(
+        source,
+        `search variable "?${variable}" does not appear in "${where}.query".`,
+      );
+    }
+    return variable;
+  });
+  const description =
+    obj.description === undefined
+      ? undefined
+      : requireString(obj.description, `${where}.search.description`, source);
+  return {
+    variables,
+    ...(description !== undefined ? { description } : {}),
+  };
+}
+
+/**
+ * Check that the query mentions the variable (`?name` or `$name`).
+ *
+ * A textual check, not a SPARQL parse — it exists to fail typos at boot
+ * instead of silently filtering every row out at first use.
+ */
+function referencesVariable(query: string, variable: string): boolean {
+  const pattern = new RegExp(`[?$]${variable}\\b`);
+  return pattern.test(query);
+}
+
+function validateFilterArray(
+  raw: unknown,
+  where: string,
+  source: string,
+): readonly StoryPackFilter[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.filters" must be a non-empty array.`,
+    );
+  }
+  const filters = raw.map((entry, index) =>
+    validateFilter(entry, `${where}.filters[${index}]`, source),
+  );
+  const seen = new Set<string>();
+  for (const filter of filters) {
+    if (seen.has(filter.param)) {
+      throw buildStoryConfigError(
+        source,
+        `duplicate filter param "${filter.param}".`,
+      );
+    }
+    seen.add(filter.param);
+  }
+  return filters;
+}
+
+function validateFilter(
+  raw: unknown,
+  where: string,
+  source: string,
+): StoryPackFilter {
+  const obj = requireObject(raw, where, source);
+  const param = requireString(obj.param, `${where}.param`, source);
+  if (!FILTER_PARAM_PATTERN.test(param)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.param" must be a single lowercase word (letters and digits, no hyphens), got "${param}".`,
+    );
+  }
+  if (RESERVED_FILTER_PARAMS.has(param)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.param" "${param}" is a reserved name.`,
+    );
+  }
+  rejectReservedObjectKey(param, `${where}.param`, source);
+  const variable = requireString(obj.variable, `${where}.variable`, source);
+  if (!FIELD_PATTERN.test(variable)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.variable" must name a SELECT variable.`,
+    );
+  }
+  rejectReservedObjectKey(variable, `${where}.variable`, source);
+  // `values` is optional (pack v1): without it the filter is a free-string
+  // parameter matched case-insensitively against the variable — used when
+  // the value set is data-driven and cannot be declared.
+  const values =
+    obj.values === undefined
+      ? undefined
+      : validateFilterValues(obj.values, where, source);
+  const description =
+    obj.description === undefined
+      ? undefined
+      : requireString(obj.description, `${where}.description`, source);
+  return {
+    param,
+    variable,
+    ...(values ? { values } : {}),
+    ...(description !== undefined ? { description } : {}),
+  };
+}
+
+function validateFilterValues(
+  raw: unknown,
+  where: string,
+  source: string,
+): readonly string[] {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.values" must be a non-empty array.`,
+    );
+  }
+  const values = raw.map((value, index) =>
+    requireString(value, `${where}.values[${index}]`, source),
+  );
+  const lowered = new Set<string>();
+  for (const value of values) {
+    const key = value.toLowerCase();
+    if (lowered.has(key)) {
+      throw buildStoryConfigError(
+        source,
+        `"${where}.values" contains duplicate value "${value}" ` +
+          "(values must be unique, case-insensitively).",
+      );
+    }
+    lowered.add(key);
+  }
+  return values;
+}
+
+function validateColumn(
+  raw: unknown,
+  where: string,
+  source: string,
+): StoryPackColumn {
+  const obj = requireObject(raw, where, source);
+  const field = requireString(obj.field, `${where}.field`, source);
+  if (!FIELD_PATTERN.test(field)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.field" must name a SELECT variable.`,
+    );
+  }
+  rejectReservedObjectKey(field, `${where}.field`, source);
+  const label =
+    obj.label === undefined
+      ? undefined
+      : requireString(obj.label, `${where}.label`, source);
+  return { field, ...(label !== undefined ? { label } : {}) };
+}
+
+function validateLookup(raw: unknown, source: string): StoryPackLookup {
+  const obj = requireObject(raw, "lookup", source);
+  const by = requirePredicateTerm(obj.by, "lookup.by", source);
+  const type =
+    obj.type === undefined
+      ? undefined
+      : requireTerm(obj.type, "lookup.type", source);
+  const description =
+    obj.description === undefined
+      ? undefined
+      : requireString(obj.description, "lookup.description", source);
+  const toolDescription =
+    obj.toolDescription === undefined
+      ? undefined
+      : requireString(obj.toolDescription, "lookup.toolDescription", source);
+
+  const fields = validateFieldArray(obj.fields, "lookup.fields", source);
+  const sections = validateSectionArray(
+    obj.sections,
+    "lookup.sections",
+    source,
+  );
+  const expand = validateExpandArray(obj.expand, "lookup.expand", source);
+  const disclosure = validateDisclosure(obj.disclosure, source);
+  const sample = validateSample(obj.sample, source);
+
+  // Cross-check: every expand `level` must name a declared disclosure level.
+  const levels = new Set(disclosure?.levels ?? []);
+  for (const entry of expand ?? []) {
+    if (entry.level !== undefined && !levels.has(entry.level)) {
+      throw buildStoryConfigError(
+        source,
+        `expand "${entry.name}" level "${entry.level}" is not a declared disclosure level.`,
+      );
+    }
+  }
+
+  return {
+    by,
+    ...(type !== undefined ? { type } : {}),
+    ...(description !== undefined ? { description } : {}),
+    ...(toolDescription !== undefined ? { toolDescription } : {}),
+    ...(fields ? { fields } : {}),
+    ...(sections ? { sections } : {}),
+    ...(expand ? { expand } : {}),
+    ...(disclosure ? { disclosure } : {}),
+    ...(sample !== undefined ? { sample } : {}),
+  };
+}
+
+function validateSample(
+  raw: unknown,
+  source: string,
+): true | StoryPackSample | undefined {
+  if (raw === undefined) return undefined;
+  if (raw === true) return true;
+  const obj = requireObject(raw, "lookup.sample", source);
+  if (obj.count !== undefined) {
+    // Authors fail fast on an out-of-range default; user-provided counts
+    // are clamped at run time by parseSampleCount instead.
+    if (
+      typeof obj.count !== "number" ||
+      !Number.isInteger(obj.count) ||
+      obj.count < MIN_SAMPLE_COUNT ||
+      obj.count > MAX_SAMPLE_COUNT
+    ) {
+      throw buildStoryConfigError(
+        source,
+        `"lookup.sample.count" must be an integer between ${MIN_SAMPLE_COUNT} and ${MAX_SAMPLE_COUNT}.`,
+      );
+    }
+  }
+  const description =
+    obj.description === undefined
+      ? undefined
+      : requireString(obj.description, "lookup.sample.description", source);
+  const toolDescription =
+    obj.toolDescription === undefined
+      ? undefined
+      : requireString(
+          obj.toolDescription,
+          "lookup.sample.toolDescription",
+          source,
+        );
+  return {
+    ...(obj.count !== undefined ? { count: obj.count as number } : {}),
+    ...(description !== undefined ? { description } : {}),
+    ...(toolDescription !== undefined ? { toolDescription } : {}),
+  };
+}
+
+function validateDisclosure(
+  raw: unknown,
+  source: string,
+): StoryPackDisclosure | undefined {
+  if (raw === undefined) return undefined;
+  const obj = requireObject(raw, "lookup.disclosure", source);
+  if (!Array.isArray(obj.levels) || obj.levels.length === 0) {
+    throw buildStoryConfigError(
+      source,
+      '"lookup.disclosure.levels" must be a non-empty array.',
+    );
+  }
+  const seen = new Set<string>();
+  const levels = obj.levels.map((value, index) => {
+    const level = requireString(
+      value,
+      `lookup.disclosure.levels[${index}]`,
+      source,
+    );
+    // Levels derive parameter names (`--detail` enum values and the alias
+    // flags), so they are held to the same single-word rule as filter
+    // params and may not shadow reserved parameter names.
+    if (!FILTER_PARAM_PATTERN.test(level)) {
+      throw buildStoryConfigError(
+        source,
+        `disclosure level "${level}" must be a single lowercase word (letters and digits, no hyphens).`,
+      );
+    }
+    if (RESERVED_LEVEL_NAMES.has(level)) {
+      throw buildStoryConfigError(
+        source,
+        `disclosure level "${level}" is a reserved name.`,
+      );
+    }
+    rejectReservedObjectKey(
+      level,
+      `lookup.disclosure.levels[${index}]`,
+      source,
+    );
+    if (seen.has(level)) {
+      throw buildStoryConfigError(
+        source,
+        `duplicate disclosure level "${level}".`,
+      );
+    }
+    seen.add(level);
+    return level;
+  });
+  const defaultLevel =
+    obj.default === undefined
+      ? undefined
+      : requireString(obj.default, "lookup.disclosure.default", source);
+  if (defaultLevel !== undefined && !seen.has(defaultLevel)) {
+    throw buildStoryConfigError(
+      source,
+      `disclosure default "${defaultLevel}" is not one of the declared levels.`,
+    );
+  }
+  return {
+    levels,
+    ...(defaultLevel !== undefined ? { default: defaultLevel } : {}),
+  };
+}
+
+function validateExpandArray(
+  raw: unknown,
+  where: string,
+  source: string,
+): readonly StoryPackExpand[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw)) {
+    throw buildStoryConfigError(source, `"${where}" must be an array.`);
+  }
+  const names = new Set<string>();
+  return raw.map((entry, index) => {
+    const expand = validateExpand(entry, `${where}[${index}]`, source);
+    if (names.has(expand.name)) {
+      throw buildStoryConfigError(
+        source,
+        `duplicate expand name "${expand.name}" in "${where}".`,
+      );
+    }
+    names.add(expand.name);
+    return expand;
+  });
+}
+
+function validateExpand(
+  raw: unknown,
+  where: string,
+  source: string,
+): StoryPackExpand {
+  const obj = requireObject(raw, where, source);
+  const name = requireString(obj.name, `${where}.name`, source);
+  if (!FIELD_PATTERN.test(name)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.name" must be a simple identifier.`,
+    );
+  }
+  rejectReservedObjectKey(name, `${where}.name`, source);
+  const relation = requirePredicateTerm(
+    obj.relation,
+    `${where}.relation`,
+    source,
+  );
+  if (obj.kind !== undefined && obj.kind !== "list" && obj.kind !== "table") {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.kind" must be "list" or "table".`,
+    );
+  }
+  if (!Array.isArray(obj.select) || obj.select.length === 0) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.select" must be a non-empty array.`,
+    );
+  }
+  const select: StoryPackExpandField[] = obj.select.map((entry, index) =>
+    validateField(entry, `${where}.select[${index}]`, source),
+  );
+  const heading =
+    obj.heading === undefined
+      ? undefined
+      : requireString(obj.heading, `${where}.heading`, source);
+  // Membership in the declared levels is cross-checked in validateLookup.
+  const level =
+    obj.level === undefined
+      ? undefined
+      : requireString(obj.level, `${where}.level`, source);
+  return {
+    name,
+    relation,
+    select,
+    ...(heading !== undefined ? { heading } : {}),
+    ...(obj.kind !== undefined ? { kind: obj.kind as "list" | "table" } : {}),
+    ...(obj.showWhenEmpty === true ? { showWhenEmpty: true } : {}),
+    ...(level !== undefined ? { level } : {}),
+  };
+}
+
+function validateFieldArray(
+  raw: unknown,
+  where: string,
+  source: string,
+): readonly StoryPackField[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw)) {
+    throw buildStoryConfigError(source, `"${where}" must be an array.`);
+  }
+  return raw.map((entry, index) =>
+    validateField(entry, `${where}[${index}]`, source),
+  );
+}
+
+function validateSectionArray(
+  raw: unknown,
+  where: string,
+  source: string,
+): readonly StoryPackSection[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw)) {
+    throw buildStoryConfigError(source, `"${where}" must be an array.`);
+  }
+  return raw.map((entry, index) => {
+    const base = validateField(entry, `${where}[${index}]`, source);
+    const obj = entry as Record<string, unknown>;
+    if (obj.kind !== undefined && obj.kind !== "field" && obj.kind !== "code") {
+      throw buildStoryConfigError(
+        source,
+        `"${where}[${index}].kind" must be "field" or "code".`,
+      );
+    }
+    return {
+      ...base,
+      ...(obj.kind !== undefined ? { kind: obj.kind as "field" | "code" } : {}),
+    };
+  });
+}
+
+function validateField(
+  raw: unknown,
+  where: string,
+  source: string,
+): StoryPackField {
+  const obj = requireObject(raw, where, source);
+  const name = requireString(obj.name, `${where}.name`, source);
+  if (!FIELD_PATTERN.test(name)) {
+    throw buildStoryConfigError(
+      source,
+      `"${where}.name" must be a simple identifier.`,
+    );
+  }
+  rejectReservedObjectKey(name, `${where}.name`, source);
+  const property = requirePredicateTerm(
+    obj.property,
+    `${where}.property`,
+    source,
+  );
+  const label =
+    obj.label === undefined
+      ? undefined
+      : requireString(obj.label, `${where}.label`, source);
+  return { name, property, ...(label !== undefined ? { label } : {}) };
+}
+
+function requireObject(
+  raw: unknown,
+  where: string,
+  source: string,
+): Record<string, unknown> {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw buildStoryConfigError(source, `"${where}" must be an object.`);
+  }
+  return raw as Record<string, unknown>;
+}
+
+function requireString(raw: unknown, where: string, source: string): string {
+  if (typeof raw !== "string" || raw.trim() === "") {
+    throw buildStoryConfigError(
+      source,
+      `"${where}" must be a non-empty string.`,
+    );
+  }
+  return raw;
+}
+
+/** Require a prefixed name (`ex:Recipe`) or an embeddable absolute IRI. */
+function requireTerm(raw: unknown, where: string, source: string): string {
+  const value = requireString(raw, where, source);
+  if (value.includes("://")) {
+    if (EMBEDDABLE_IRI_PATTERN.test(value)) return value;
+    throw buildStoryConfigError(
+      source,
+      `"${where}" is not a valid IRI (no whitespace or <>" characters).`,
+    );
+  }
+  if (PREFIXED_NAME_PATTERN.test(value)) return value;
+  throw buildStoryConfigError(
+    source,
+    `"${where}" must be a prefixed name (ex:Recipe) or an absolute IRI.`,
+  );
+}
+
+/**
+ * Require a predicate term: a single term or a slash-separated SPARQL
+ * property path of prefixed names (`cs:hasCategory/cs:slug`).
+ *
+ * Paths are only meaningful in predicate position (`lookup.by` and
+ * `fields[].property`/`sections[].property`); class terms go through
+ * `requireTerm` and reject paths.
+ */
+function requirePredicateTerm(
+  raw: unknown,
+  where: string,
+  source: string,
+): string {
+  const value = requireString(raw, where, source);
+  if (value.includes("://") || !value.includes("/")) {
+    return requireTerm(value, where, source);
+  }
+  const segments = value.split("/");
+  for (const segment of segments) {
+    if (!PREFIXED_NAME_PATTERN.test(segment)) {
+      throw buildStoryConfigError(
+        source,
+        `"${where}" property path segment "${segment}" must be a prefixed name.`,
+      );
+    }
+  }
+  return value;
+}
+
+function buildStoryConfigError(source: string, message: string): PragmaError {
+  return PragmaError.configError(`Invalid story in ${source}: ${message}`);
+}