@anthusai/papyrus 1.3.0 → 1.4.0-next.10

package/lib/site-section-suggestions.ts

@@ -0,0 +1,120 @@
+import type { SemanticRelationRecord } from "./category-repository";
+import { MINIMUM_COMPARISONS_FOR_AGREEMENT, SHADOW_AGREEMENT_SCHEMA } from "./cyclotron-suggestions";
+
+export const SITE_DECISION_RELATION = "site_decision_is";
+export const SECTION_SELECTOR_CLASSIFIER_PREFIX = "section-selector-";
+export const SECTION_FIT_CLASSIFIER_PREFIX = "section-fit-";
+
+/** The site cyclotron's suggested Section for one reference. Advisory only. */
+export type SectionSuggestion = {
+  decisionRelationId: string;
+  cyclotronId: string | null;
+  sectionId: string;
+  confidence: number | null;
+  /** Section id to probability, highest first. */
+  probabilities: Array<{ sectionId: string; probability: number }>;
+  decidedAt: string | null;
+};
+
+/** How often the suggestion of one Section matched what editors later decided. */
+export type SectionAgreement = {
+  sectionId: string;
+  comparisons: number;
+  agreement: number | null;
+  precision: number | null;
+  recall: number | null;
+};
+
+export type SiteSectionAgreement = {
+  computedAt: string | null;
+  selectorAccuracy: number | null;
+  selectorComparisons: number;
+  sections: SectionAgreement[];
+};
+
+function parseMetadata(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, unknown>;
+  if (typeof value !== "string") return {};
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function numberOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/** The part of `<cyclotronId>/<classifier>` after the last slash. */
+export function siteClassifierName(classifierKey: string): string {
+  return classifierKey.slice(classifierKey.lastIndexOf("/") + 1);
+}
+
+/**
+ * Current suggested Sections keyed by reference lineage, from the relations the
+ * Newsroom already loads. Only the section-selector classifier names a Section.
+ */
+export function currentSectionSuggestions(relations: SemanticRelationRecord[]): Map<string, SectionSuggestion> {
+  const suggestions = new Map<string, SectionSuggestion>();
+  for (const relation of relations) {
+    if (relation.predicate !== SITE_DECISION_RELATION || relation.relationState !== "current") continue;
+    if (!siteClassifierName(relation.classifierId ?? "").startsWith(SECTION_SELECTOR_CLASSIFIER_PREFIX)) continue;
+    const metadata = parseMetadata(relation.metadata);
+    const sectionId = typeof metadata.label === "string" ? metadata.label : "";
+    if (!sectionId) continue;
+    const rawProbabilities = parseMetadata(metadata.probabilities);
+    const probabilities = Object.entries(rawProbabilities)
+      .flatMap(([candidate, probability]) => (numberOrNull(probability) === null ? [] : [{ sectionId: candidate, probability: probability as number }]))
+      .sort((left, right) => right.probability - left.probability);
+    suggestions.set(relation.subjectLineageId, {
+      decisionRelationId: relation.id,
+      cyclotronId: typeof metadata.cyclotronId === "string" ? metadata.cyclotronId : null,
+      sectionId,
+      confidence: numberOrNull(relation.confidence) ?? probabilities.find((entry) => entry.sectionId === sectionId)?.probability ?? null,
+      probabilities,
+      decidedAt: typeof metadata.decidedAt === "string" ? metadata.decidedAt : null,
+    });
+  }
+  return suggestions;
+}
+
+/** The site cyclotron's id, from any current Section suggestion. */
+export function siteCyclotronIdOf(suggestions: Map<string, SectionSuggestion>): string | null {
+  for (const suggestion of suggestions.values()) if (suggestion.cyclotronId) return suggestion.cyclotronId;
+  return null;
+}
+
+/** The per-Section part of a cyclotron-shadow-agreement/v1 payload the site sweep wrote, or null for any other JSON. */
+export function parseSiteSectionAgreement(json: unknown): SiteSectionAgreement | null {
+  if (!json || typeof json !== "object") return null;
+  const record = json as Record<string, unknown>;
+  if (record.schema !== SHADOW_AGREEMENT_SCHEMA) return null;
+  const classifiers = record.classifiers;
+  if (!classifiers || typeof classifiers !== "object") return null;
+  const sections: SectionAgreement[] = [];
+  for (const [classifier, value] of Object.entries(classifiers as Record<string, unknown>)) {
+    if (!classifier.startsWith(SECTION_FIT_CLASSIFIER_PREFIX) || !value || typeof value !== "object") continue;
+    const metrics = value as Record<string, unknown>;
+    sections.push({
+      sectionId: classifier.slice(SECTION_FIT_CLASSIFIER_PREFIX.length),
+      comparisons: numberOrNull(metrics.comparisons) ?? 0,
+      agreement: numberOrNull(metrics.agreement),
+      precision: numberOrNull(metrics.precision),
+      recall: numberOrNull(metrics.recall),
+    });
+  }
+  if (!sections.length && numberOrNull(record.selectorAccuracy) === null) return null;
+  return {
+    computedAt: typeof record.computedAt === "string" ? record.computedAt : null,
+    selectorAccuracy: numberOrNull(record.selectorAccuracy),
+    selectorComparisons: numberOrNull(record.comparisons) ?? 0,
+    sections,
+  };
+}
+
+/** Agreement figures are worth showing only once enough editor decisions followed a suggestion. */
+export function sectionAgreementIsMeasured(agreement: SectionAgreement | undefined): boolean {
+  return Boolean(agreement) && (agreement as SectionAgreement).comparisons >= MINIMUM_COMPARISONS_FOR_AGREEMENT && (agreement as SectionAgreement).agreement !== null;
+}

package/lib/site-stack.ts

@@ -149,7 +149,7 @@ export const PILOBOL_US_THEME_PACK_TOKENS: ThemePackTokens = {
 };
 
 /**
- * Anthus palette, read off the live Gatsby site at `AnthusAI/Anth.us`
+ * Anthus palette, read off the live Gatsby site at `AnthusAI/Anth.us-legacy-Gatsby`
  * (`src/styles/variables.scss` `:root`). Colors only — Shadcn owns typography.
  * Mapping from that file's names to the pack's slots:
  *

package/lib/story-reporting-trail.ts

@@ -0,0 +1,106 @@
+/**
+ * Everything the reporting process recorded about one story, gathered by the story's lineage id:
+ * the draft versions of the copy, the research, reporting and copywriting assignments with their events,
+ * the notes and packets in the threads anchored to the story or its assignments, the references it draws on,
+ * and attached files. See docs/content-item-lifecycle.md for how these records join.
+ */
+export type TrailVersion = {
+  id: string;
+  versionNumber: number;
+  versionState: string | null;
+  status: string | null;
+  stage: string | null;
+  headline: string | null;
+  changeReason: string | null;
+  versionCreatedBy: string | null;
+  versionCreatedAt: string | null;
+  updatedAt: string | null;
+};
+
+export type TrailAssignmentEvent = {
+  id: string;
+  eventType: string;
+  fromStatus: string | null;
+  toStatus: string | null;
+  actorLabel: string | null;
+  note: string | null;
+  createdAt: string;
+};
+
+export type TrailAssignment = {
+  id: string;
+  title: string;
+  assignmentTypeKey: string;
+  status: string;
+  assigneeKey: string | null;
+  summary: string | null;
+  createdAt: string;
+  events: TrailAssignmentEvent[];
+};
+
+export type TrailMessage = {
+  id: string;
+  sequenceNumber?: number | null;
+  messageKind: string | null;
+  authorLabel: string | null;
+  summary: string | null;
+  content: string | null;
+  createdAt: string;
+};
+
+export type TrailThread = {
+  id: string;
+  title: string | null;
+  threadKind: string | null;
+  summary: string | null;
+  messages: TrailMessage[];
+};
+
+export type TrailReference = {
+  relationId: string;
+  predicate: string;
+  referenceId: string;
+  referenceLineageId: string | null;
+  title: string | null;
+  sourceUri: string | null;
+  /** consulted: read during reporting; cited: a citation in the article. */
+  role: "consulted" | "cited";
+  note: string | null;
+  citationKey: string | null;
+  addedBy: string | null;
+  addedAt: string | null;
+};
+
+export type TrailAttachment = {
+  id: string;
+  role: string | null;
+  filename: string | null;
+  mediaType: string | null;
+  byteSize: number | null;
+};
+
+export type StoryReportingTrail = {
+  versions: TrailVersion[];
+  assignments: TrailAssignment[];
+  threads: TrailThread[];
+  references: TrailReference[];
+  attachments: TrailAttachment[];
+};
+
+export const EMPTY_STORY_REPORTING_TRAIL: StoryReportingTrail = { versions: [], assignments: [], threads: [], references: [], attachments: [] };
+
+export function storyReportingTrailIsEmpty(trail: StoryReportingTrail): boolean {
+  return trail.assignments.length === 0 && trail.threads.length === 0 && trail.references.length === 0 && trail.attachments.length === 0 && trail.versions.length <= 1;
+}
+
+export type StoryFeedEntry =
+  | ({ entryKind: "message"; threadTitle: string | null } & TrailMessage)
+  | { entryKind: "reference"; id: string; createdAt: string; reference: TrailReference };
+
+/** Every message of the story's threads and every reference found for it in one chronological feed, newest first. */
+export function storyMessageFeed(trail: StoryReportingTrail): StoryFeedEntry[] {
+  const messages: StoryFeedEntry[] = trail.threads.flatMap(thread => thread.messages.map(message => ({ ...message, entryKind: "message" as const, threadTitle: thread.title })));
+  const references: StoryFeedEntry[] = trail.references.filter(reference => reference.addedAt).map(reference => ({ entryKind: "reference" as const, id: `reference-${reference.relationId}`, createdAt: reference.addedAt as string, reference }));
+  const sequenceOf = (entry: StoryFeedEntry) => (entry.entryKind === "message" ? entry.sequenceNumber ?? 0 : 0);
+  return [...messages, ...references].sort((left, right) => right.createdAt.localeCompare(left.createdAt) || sequenceOf(right) - sequenceOf(left));
+}

package/lib/tenant-keys.ts

@@ -0,0 +1,32 @@
+export const TENANT_ID_ENVIRONMENT_VARIABLE = "PAPYRUS_TENANT_ID";
+const TENANT_KEY_SEPARATOR = "#";
+const TENANT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
+
+export function validateTenantId(tenantId: string): string {
+  if (!TENANT_ID_PATTERN.test(tenantId)) {
+    throw new Error(`Tenant id "${tenantId}" must be lowercase letters, digits and hyphens, starting with a letter or digit.`);
+  }
+  return tenantId;
+}
+
+export function tenantIdFromEnvironment(environment: NodeJS.ProcessEnv = process.env): string | undefined {
+  const configured = environment[TENANT_ID_ENVIRONMENT_VARIABLE]?.trim();
+  return configured ? validateTenantId(configured) : undefined;
+}
+
+export function tenantScopedValue(tenantId: string | undefined, value: string): string {
+  if (!tenantId) return value;
+  const prefix = `${tenantId}${TENANT_KEY_SEPARATOR}`;
+  return value.startsWith(prefix) ? value : `${prefix}${value}`;
+}
+
+export function rowBelongsToTenant(tenantId: string | undefined, row: { tenantId?: string | null } | null | undefined): boolean {
+  if (!tenantId || !row) return true;
+  return row.tenantId === tenantId;
+}
+
+/** The tenant a Prospectus publishing account maps to: its id as lowercase letters, digits and hyphens. */
+export function tenantIdForProspectusAccount(accountId: string | null | undefined): string | undefined {
+  const normalized = (accountId ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 63);
+  return normalized ? validateTenantId(normalized) : undefined;
+}

package/lib/text-columns.ts

@@ -0,0 +1,251 @@
+import { type ArticlePublicationItem, getPublicationItemText } from "./publication-items";
+import {
+  type LayoutCursor,
+  layoutTextLines,
+  type PreparedTextWithSegments,
+  prepareWithSegmentsCached,
+  type TextLine,
+  type TextObstacle,
+} from "./pretext-layout";
+import { reserveRhythmRows, type VerticalRhythm } from "./blog-rhythm";
+import {
+  type FurnitureSufficiencyReport,
+  type LayoutConfig,
+  type SolvedChromeBox,
+  type SolvedFurniture,
+} from "./layout-types";
+import { SERIF_TEXT_FONT, clamp, getSpanWidth } from "./layout-config";
+import { rectsOverlap } from "./furniture";
+
+export function layoutTextColumns({
+  item,
+  cursor,
+  columnCount,
+  textHeight,
+  maximumTextHeightByColumn = [],
+  localConfig,
+  furniture,
+  chromeBoxes = [],
+  furnitureObstacleOffsetY = 0,
+  furnitureObstacleMarginBottom = 0,
+  minimumLineStartYByColumn = [],
+}: {
+  item: ArticlePublicationItem;
+  cursor: LayoutCursor;
+  columnCount: number;
+  textHeight: number;
+  maximumTextHeightByColumn?: number[];
+  localConfig: LayoutConfig;
+  furniture: SolvedFurniture[];
+  chromeBoxes?: SolvedChromeBox[];
+  furnitureObstacleOffsetY?: number;
+  furnitureObstacleMarginBottom?: number;
+  minimumLineStartYByColumn?: number[];
+}): { columns: TextLine[][]; cursor: LayoutCursor; hasMore: boolean } {
+  const columns: TextLine[][] = [];
+  const preparedText = getPrepared(item, localConfig.bodyFont);
+  const columnWidth = getSpanWidth(localConfig, 1);
+  let current = { ...cursor };
+  let hasMore = true;
+
+  for (let columnIndex = 0; columnIndex < columnCount; columnIndex += 1) {
+    const result = layoutTextLines({
+      prepared: preparedText,
+      cursor: current,
+      maxHeight: maximumTextHeightByColumn[columnIndex] ?? textHeight,
+      maxWidth: columnWidth,
+      lineHeight: localConfig.lineHeight,
+      linePaintHeight: localConfig.linePaintHeight,
+      fontSize: localConfig.bodyFontSize,
+      fontFamily: SERIF_TEXT_FONT,
+      obstacles: getColumnTextObstacles(
+        furniture,
+        columnIndex,
+        chromeBoxes,
+        furnitureObstacleOffsetY,
+        furnitureObstacleMarginBottom,
+        minimumLineStartYByColumn[columnIndex] ?? 0,
+      ),
+    });
+    columns.push(result.lines);
+    current = result.cursor;
+    hasMore = result.hasMore;
+    if (!hasMore) {
+      while (columns.length < columnCount) columns.push([]);
+      break;
+    }
+  }
+
+  return { columns, cursor: current, hasMore };
+}
+
+export function getPrepared(article: ArticlePublicationItem, font: string): PreparedTextWithSegments {
+  return prepareWithSegmentsCached(getPublicationItemText(article), font, { whiteSpace: "pre-wrap" });
+}
+
+export function getLineLimitHeight(maxLines: number, lineHeight: number, linePaintHeight: number, rhythm: VerticalRhythm): number {
+  if (maxLines <= 0) return 0;
+  return reserveRhythmRows((maxLines - 1) * lineHeight + linePaintHeight, rhythm);
+}
+
+function getColumnTextObstacles(
+  furniture: SolvedFurniture[],
+  columnIndex: number,
+  chromeBoxes: SolvedChromeBox[] = [],
+  furnitureOffsetY = 0,
+  furnitureMarginBottom = 0,
+  minimumLineStartY = 0,
+): TextObstacle[] {
+  const topObstacle: TextObstacle[] = minimumLineStartY > 0
+    ? [{ x: 0, y: 0, width: Number.POSITIVE_INFINITY, height: minimumLineStartY }]
+    : [];
+  const furnitureObstacles = furniture
+    .filter((item) => item.wrapsText && columnIndex >= item.columnStart && columnIndex < item.columnStart + item.columnSpan)
+    .map((item) => ({
+      x: 0,
+      y: item.y + furnitureOffsetY,
+      width: Number.POSITIVE_INFINITY,
+      height: item.height + getFurnitureObstacleMarginBottom(item, furnitureMarginBottom),
+    }));
+  const imageClearanceObstacles = furniture
+    .filter((item) => (
+      item.kind === "image" &&
+      item.wrapsText &&
+      furnitureMarginBottom > 0 &&
+      columnIndex >= item.columnStart &&
+      columnIndex < item.columnStart + item.columnSpan
+    ))
+    .map((item) => ({
+      x: 0,
+      y: item.y + furnitureOffsetY + item.height,
+      width: Number.POSITIVE_INFINITY,
+      height: furnitureMarginBottom,
+    }));
+  const chromeObstacles = chromeBoxes
+    .filter((box) => columnIndex >= box.columnStart && columnIndex < box.columnStart + box.columnSpan)
+    .map((box) => ({
+      x: 0,
+      y: box.y,
+      width: Number.POSITIVE_INFINITY,
+      height: box.height,
+    }));
+  return [...topObstacle, ...furnitureObstacles, ...imageClearanceObstacles, ...chromeObstacles];
+}
+
+function getFurnitureObstacleMarginBottom(item: SolvedFurniture, marginBottom: number): number {
+  return item.kind === "image" || item.kind === "pullQuote" ? marginBottom : 0;
+}
+
+export function getColumnWhitespace(columns: TextLine[][], textHeight: number, furniture: SolvedFurniture[]): number {
+  return columns.reduce(
+    (total, column, columnIndex) =>
+      total + Math.max(0, textHeight - getLinesHeight(column) - getColumnObstacleHeight(furniture, columnIndex, textHeight)),
+    0,
+  );
+}
+
+export function getFurnitureSufficiencyReport({
+  columns,
+  textHeight,
+  furniture,
+  hasMore,
+  config,
+}: {
+  columns: TextLine[][];
+  textHeight: number;
+  furniture: SolvedFurniture[];
+  hasMore: boolean;
+  config: LayoutConfig;
+}): FurnitureSufficiencyReport {
+  const visibleRows = columns.reduce((total, column) => total + column.length, 0);
+  const furnitureRows = furniture.reduce(
+    (total, item) => total + getFurnitureRowBurden(item, config.rhythm.rowHeight),
+    0,
+  );
+  const accepted = (reason?: string): FurnitureSufficiencyReport => ({
+    accepted: !reason,
+    reason,
+    visibleRows,
+    furnitureRows,
+  });
+
+  if (furniture.length === 0 || furnitureRows === 0) return accepted();
+  const overlapReason = getFurnitureOverlapReason(furniture);
+  if (overlapReason) return accepted(overlapReason);
+  const minimumReadableRows = columns.length * (furniture.some((item) => item.kind === "pullQuote") ? 6 : 3);
+  if (visibleRows * 4 < furnitureRows) {
+    return accepted("visible-copy-far-below-furniture-burden");
+  }
+  if (visibleRows < furnitureRows && visibleRows < minimumReadableRows) {
+    return accepted("visible-copy-below-furniture-burden");
+  }
+
+  const finalTextColumnIndex = columns.reduce((lastIndex, column, columnIndex) => (
+    column.length > 0 ? columnIndex : lastIndex
+  ), -1);
+  const exhausted = !hasMore;
+  for (let columnIndex = 0; columnIndex < columns.length; columnIndex += 1) {
+    const visibleColumnRows = columns[columnIndex].length;
+    const obstacleRows = Math.ceil(getColumnObstacleHeight(furniture, columnIndex, textHeight) / config.rhythm.rowHeight);
+    const availableRows = Math.floor(textHeight / config.rhythm.rowHeight) - obstacleRows;
+    const hasSubstantialFurniture = obstacleRows >= 6;
+    const isAfterExhaustedText = exhausted && columnIndex > finalTextColumnIndex;
+    if (!hasSubstantialFurniture && !isAfterExhaustedText && availableRows >= 3 && visibleColumnRows < 3) {
+      return accepted("open-column-below-minimum-copy");
+    }
+    if (!hasSubstantialFurniture && visibleColumnRows === 1 && columnIndex < finalTextColumnIndex) {
+      return accepted("non-final-column-single-copy-row");
+    }
+  }
+
+  return accepted();
+}
+
+function getFurnitureRowBurden(item: SolvedFurniture, rowHeight: number): number {
+  if (item.kind !== "image" && item.kind !== "pullQuote") return 0;
+  return Math.ceil(item.height / rowHeight) * item.columnSpan;
+}
+
+function getFurnitureOverlapReason(furniture: SolvedFurniture[]): string | undefined {
+  for (let firstIndex = 0; firstIndex < furniture.length; firstIndex += 1) {
+    for (let secondIndex = firstIndex + 1; secondIndex < furniture.length; secondIndex += 1) {
+      if (rectsOverlap(furniture[firstIndex], furniture[secondIndex])) return "furniture-overlap";
+    }
+  }
+  return undefined;
+}
+
+function getColumnObstacleHeight(furniture: SolvedFurniture[], columnIndex: number, textHeight: number): number {
+  const intervals = furniture
+    .filter((item) => item.wrapsText && columnIndex >= item.columnStart && columnIndex < item.columnStart + item.columnSpan)
+    .map((item) => ({
+      start: clamp(item.y, 0, textHeight),
+      end: clamp(item.y + item.height, 0, textHeight),
+    }))
+    .filter((interval) => interval.end > interval.start)
+    .sort((a, b) => a.start - b.start);
+
+  const merged: Array<{ start: number; end: number }> = [];
+  for (const interval of intervals) {
+    const previous = merged[merged.length - 1];
+    if (previous && interval.start <= previous.end) previous.end = Math.max(previous.end, interval.end);
+    else merged.push({ ...interval });
+  }
+  return merged.reduce((total, interval) => total + interval.end - interval.start, 0);
+}
+
+export function getDeadColumnCount(columns: TextLine[][], textHeight: number, furniture: SolvedFurniture[]): number {
+  return columns.reduce((count, column, columnIndex) => {
+    if (column.length > 0) return count;
+    const obstacleHeight = getColumnObstacleHeight(furniture, columnIndex, textHeight);
+    return obstacleHeight >= Math.min(96, textHeight * 0.18) ? count : count + 1;
+  }, 0);
+}
+
+export function getLinesHeight(lines: TextLine[]): number {
+  return lines.length === 0 ? 0 : Math.max(...lines.map((line) => line.y + line.paintHeight));
+}
+
+export function getFurnitureBottom(furniture: SolvedFurniture[]): number {
+  return furniture.reduce((bottom, item) => Math.max(bottom, item.y + item.height), 0);
+}

package/lib/wiki.ts

@@ -0,0 +1,56 @@
+import type { SemanticNodeRecord } from "./category-repository";
+
+/** The wiki's front page is an ordinary content item with this slug; its Markus body holds the dynamic components. */
+export const WIKI_INDEX_SLUG = "wiki-index";
+export const WIKI_PAGE_ITEM_TYPE = "wiki_page";
+export const WIKI_CONCEPT_LINK_SCHEME = "concept:";
+
+export const DEFAULT_WIKI_INDEX_MARKUS = `# Concept wiki
+
+Every page in this wiki is a concept: an entity in the knowledge graph that the newsroom has reported on, researched or cited. Open one to see what it is, what it connects to, and the references behind it.
+
+## Recently edited
+
+::recent-concepts{limit=10}
+
+## Browse all concepts
+
+::concept-list
+`;
+
+export function conceptEditedAt(node: SemanticNodeRecord): string {
+  return node.updatedAt ?? node.versionCreatedAt ?? node.createdAt ?? "";
+}
+
+export function conceptTitle(node: SemanticNodeRecord): string {
+  return node.displayName?.trim() || node.nodeKey;
+}
+
+export function conceptId(node: SemanticNodeRecord): string {
+  return node.lineageId ?? node.id;
+}
+
+export function recentlyEditedConcepts(nodes: readonly SemanticNodeRecord[], options: { limit?: number; kind?: string | null } = {}): SemanticNodeRecord[] {
+  const { limit = 10, kind = null } = options;
+  return nodes
+    .filter(node => !kind || node.nodeKind === kind)
+    .slice()
+    .sort((left, right) => conceptEditedAt(right).localeCompare(conceptEditedAt(left)) || conceptTitle(left).localeCompare(conceptTitle(right)))
+    .slice(0, limit);
+}
+
+export function conceptsByTitle(nodes: readonly SemanticNodeRecord[], options: { kind?: string | null; limit?: number | null } = {}): SemanticNodeRecord[] {
+  const filtered = nodes.filter(node => !options.kind || node.nodeKind === options.kind).slice().sort((left, right) => conceptTitle(left).localeCompare(conceptTitle(right)));
+  return options.limit ? filtered.slice(0, options.limit) : filtered;
+}
+
+/** Finds the concept a `concept:<key>` wiki link names, by lineage id, node key or title. */
+export function resolveConceptLink(href: string, nodes: readonly SemanticNodeRecord[]): SemanticNodeRecord | null {
+  if (!href.startsWith(WIKI_CONCEPT_LINK_SCHEME)) return null;
+  const reference = decodeURIComponent(href.slice(WIKI_CONCEPT_LINK_SCHEME.length)).trim().toLowerCase();
+  return nodes.find(node => conceptId(node).toLowerCase() === reference || node.nodeKey.toLowerCase() === reference || conceptTitle(node).toLowerCase() === reference) ?? null;
+}
+
+export function conceptWikiPath(node: SemanticNodeRecord): string {
+  return `/newsroom/concepts/${encodeURIComponent(conceptId(node))}`;
+}