@anthusai/papyrus 1.3.0 → 1.4.0-next.10

package/lib/content-actions-demo.ts

@@ -1,4 +1,5 @@
 import { ContentActionFailure } from "./content-actions-client";
+import { isLocalPreviewEnabled } from "./local-preview";
 import type {
   DeriveMarkusInput,
   DeriveMarkusResult,
@@ -12,6 +13,7 @@ import {
   demoContentHash,
   type DemoArticleRecord,
 } from "./newsroom-demo-articles";
+import { createLocalPreviewEditableArticle, lineageForPreviewVersion, recordLocalPreviewDesk, recordLocalPreviewVersion } from "./local-preview-seed";
 import { sourceLineOffset, type ArticlesBackend, type EditableArticle, type NewsroomArticleRow } from "./newsroom-articles";
 
 function titleFromYaml(frontMatterYaml: string | null, fallback: string): string {
@@ -29,6 +31,18 @@ function demoAttribute(attributes: string, name: string): string {
   return match ? match[1] : "";
 }
 
+async function deriveThroughPreviewMarkusEngine(input: DeriveMarkusInput): Promise<DeriveMarkusResult | null> {
+  try {
+    const response = await fetch("/api/local-preview/derive", { method: "POST", body: JSON.stringify({ frontMatterYaml: input.frontMatterYaml, bodyMarkus: input.bodyMarkus }) });
+    if (!response.ok) return null;
+    const result = await response.json() as DeriveMarkusResult & { error?: string };
+    if (result.error) return null;
+    return input.includeIr ? result : { ...result, bodyIr: undefined };
+  } catch {
+    return null;
+  }
+}
+
 function demoEnvelope(bodyMarkus: string) {
   const images: Record<string, Record<string, unknown>> = {};
   const children = bodyMarkus
@@ -73,6 +87,10 @@ export function createDemoArticlesBackend(): ArticlesBackend {
   return {
     actions: {
       async deriveMarkus(input: DeriveMarkusInput): Promise<DeriveMarkusResult> {
+        if (isLocalPreviewEnabled()) {
+          const derived = await deriveThroughPreviewMarkusEngine(input);
+          if (derived) return derived;
+        }
         const lines = input.bodyMarkus.split("\n");
         const invalidIndex = lines.findIndex((line) => line.includes(":::nope"));
         if (invalidIndex >= 0) {
@@ -90,6 +108,28 @@ export function createDemoArticlesBackend(): ArticlesBackend {
       },
       async saveItemDraft(input: SaveItemDraftInput): Promise<SaveItemDraftResult> {
         const existing = input.id ? requireRecord(input.id) : null;
+        if (input.newVersion && existing) {
+          const lineageId = createLocalPreviewEditableArticle(existing.id)?.lineageId ?? existing.id;
+          const versionNumber = (existing.versionNumber ?? 1) + 1;
+          const id = `${lineageId}-v${versionNumber}`;
+          const frontMatterYaml = input.frontMatterYaml ?? "";
+          const record: DemoArticleRecord = {
+            ...existing,
+            id,
+            slug: existing.slug,
+            section: input.section,
+            title: titleFromYaml(input.frontMatterYaml, existing.slug),
+            status: "draft",
+            frontMatterYaml,
+            bodyMarkus: input.bodyMarkus,
+            contentHash: demoContentHash(frontMatterYaml, input.bodyMarkus),
+            versionNumber,
+            updatedAt: new Date().toISOString(),
+          };
+          records.set(id, record);
+          recordLocalPreviewVersion(lineageId, { id, versionNumber, versionState: "current", status: "draft", stage: null, headline: record.title, changeReason: input.changeReason ?? null, versionCreatedBy: "You", versionCreatedAt: record.updatedAt, updatedAt: record.updatedAt });
+          return { ok: true, item: { id, contentHash: record.contentHash, status: "draft", slug: record.slug, versionNumber } };
+        }
         if (existing && input.expectedContentHash !== null && input.expectedContentHash !== existing.contentHash) {
           throw new ContentActionFailure([
             { code: "conflict", message: "The item changed since it was loaded.", line: null },
@@ -119,6 +159,7 @@ export function createDemoArticlesBackend(): ArticlesBackend {
           updatedAt: new Date().toISOString(),
         };
         records.set(id, record);
+        recordLocalPreviewDesk(id, record.section);
         return {
           ok: true,
           item: {
@@ -171,9 +212,23 @@ export function createDemoArticlesBackend(): ArticlesBackend {
         .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
     },
     async loadArticle(id: string): Promise<EditableArticle> {
+      if (!records.has(id)) {
+        const previewRecord = createLocalPreviewEditableArticle(id);
+        if (previewRecord) {
+          records.set(id, {
+            ...previewRecord,
+            title: titleFromYaml(previewRecord.frontMatterYaml, previewRecord.slug),
+            status: previewRecord.status === "published" ? "published" : "draft",
+            contentHash: demoContentHash(previewRecord.frontMatterYaml, previewRecord.bodyMarkus),
+            publishedContentHash: previewRecord.status === "published" ? demoContentHash(previewRecord.frontMatterYaml, previewRecord.bodyMarkus) : null,
+            updatedAt: new Date().toISOString(),
+          });
+        }
+      }
       const record = requireRecord(id);
       return {
         id: record.id,
+        lineageId: createLocalPreviewEditableArticle(record.id)?.lineageId ?? lineageForPreviewVersion(record.id),
         type: record.type,
         section: record.section,
         slug: record.slug,

package/lib/content-item-lifecycle.ts

@@ -7,17 +7,29 @@
 export type ContentItemStageDefinition = {
   key: string;
   label: string;
+  /** Closed or rarely visited stage: its board column starts collapsed and its cards load only when it is opened. */
+  collapsedUntilOpened?: boolean;
 };
 
+export const PUBLISHED_STAGE_KEY = "published";
+
+/** Stage keys written before the story stages were simplified, read as the stage that replaced them. */
+export const LEGACY_CONTENT_ITEM_STAGE_ALIASES: Readonly<Record<string, string>> = {
+  research: "reporting",
+  report: "reporting",
+  editor_select: "reporting",
+};
+
+/** Stages for work that has not become a story yet; they appear on the assignments board only. */
+export const ASSIGNMENT_PHASE_STAGE_KEYS: readonly string[] = ["idea", "assignment"];
+
 export const DEFAULT_CONTENT_ITEM_STAGE_DEFINITIONS: readonly ContentItemStageDefinition[] = [
-  { key: "idea", label: "Idea" },
-  { key: "assignment", label: "Assignment" },
-  { key: "research", label: "Research" },
-  { key: "report", label: "Report" },
-  { key: "editor_select", label: "Editor select" },
+  { key: "reporting", label: "Reporting" },
   { key: "copywriting", label: "Copywriting" },
   { key: "illustration", label: "Illustration" },
   { key: "typesetting", label: "Typesetting" },
+  { key: "spiked", label: "Spiked", collapsedUntilOpened: true },
+  { key: "held", label: "Held" },
   { key: "published", label: "Published" },
 ];
 
@@ -25,6 +37,21 @@ export function contentItemStageKeys(stageDefinitions: readonly ContentItemStage
   return stageDefinitions.map(definition => definition.key);
 }
 
+export function canonicalContentItemStage(
+  stage: string,
+  stageDefinitions: readonly ContentItemStageDefinition[] = DEFAULT_CONTENT_ITEM_STAGE_DEFINITIONS,
+): string {
+  const isDefined = stageDefinitions.some(definition => definition.key === stage);
+  return isDefined ? stage : LEGACY_CONTENT_ITEM_STAGE_ALIASES[stage] ?? stage;
+}
+
+export function legacyStageKeysToLoad(stageDefinitions: readonly ContentItemStageDefinition[]): string[] {
+  const definedKeys = contentItemStageKeys(stageDefinitions);
+  return Object.entries(LEGACY_CONTENT_ITEM_STAGE_ALIASES)
+    .filter(([legacyKey, replacementKey]) => !definedKeys.includes(legacyKey) && definedKeys.includes(replacementKey))
+    .map(([legacyKey]) => legacyKey);
+}
+
 export function contentItemStageLabel(
   stage: string,
   stageDefinitions: readonly ContentItemStageDefinition[] = DEFAULT_CONTENT_ITEM_STAGE_DEFINITIONS,
@@ -41,6 +68,8 @@ export type ContentItemVersionRecord = {
   status: string;
   title?: string | null;
   headline?: string | null;
+  deck?: string | null;
+  metadata?: unknown;
   slug: string;
   section?: string | null;
   updatedAt?: string | null;

package/lib/content-source-context.ts

@@ -1,10 +1,13 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { getContentSource, type ContentSource } from "./site-env";
+import { tenantIdFromEnvironment } from "./tenant-keys";
 
 export type ContentSourceContext = {
   source: ContentSource;
   /** Request-scoped data client (drafts mode: carries the visitor's session cookies). */
   client?: unknown;
+  /** Tenant of the selected Prospectus account; falls back to PAPYRUS_TENANT_ID. */
+  tenantId?: string;
 };
 
 const contentSourceStorage = new AsyncLocalStorage<ContentSourceContext>();
@@ -13,8 +16,13 @@ export function runWithContentSource<T>(
   source: ContentSource,
   operation: () => Promise<T>,
   client?: unknown,
+  tenantId?: string,
 ): Promise<T> {
-  return contentSourceStorage.run({ source, client }, operation);
+  return contentSourceStorage.run({ source, client, tenantId }, operation);
+}
+
+export function currentTenantId(): string | undefined {
+  return contentSourceStorage.getStore()?.tenantId ?? tenantIdFromEnvironment();
 }
 
 export function currentRequestClient<T>(): T | undefined {

package/lib/curation-delegation-helpers.ts

@@ -0,0 +1,69 @@
+export type CurationDelegationState = "pending" | "approved" | "denied" | "expired" | "revoked";
+
+export type CurationDelegationRecord = {
+  delegationId: string;
+  agentLabel: string;
+  grantorLabel: string | null;
+  expiresAt: string;
+  revokedAt: string | null;
+  state?: CurationDelegationState | null;
+  /** XXXX-XXXX, present only while the request is pending. */
+  userCode?: string | null;
+  requestedHours?: number | null;
+  pendingExpiresAt?: string | null;
+  approvedAt?: string | null;
+  deniedAt?: string | null;
+};
+
+export function delegationExpiryText(expiresAt: string, revokedAt: string | null, nowMilliseconds: number): string {
+  if (revokedAt) return "Revoked";
+  const remaining = Date.parse(expiresAt) - nowMilliseconds;
+  if (!Number.isFinite(remaining) || remaining <= 0) return "Expired";
+  const minutes = Math.ceil(remaining / 60_000);
+  if (minutes < 60) return `Expires in ${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+  const hours = Math.round(remaining / 3_600_000);
+  return `Expires in ${hours} ${hours === 1 ? "hour" : "hours"}`;
+}
+
+export function isDelegationActive(record: CurationDelegationRecord, nowMilliseconds: number): boolean {
+  return !record.revokedAt && Date.parse(record.expiresAt) > nowMilliseconds;
+}
+
+export function describeDelegationError(error: unknown): string {
+  const raw = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  const graphql = (error as { errors?: Array<{ message?: string }> } | null)?.errors?.[0]?.message ?? "";
+  const text = `${raw} ${graphql}`.toLowerCase();
+  if (text.includes("not authorized") || text.includes("unauthorized")) return "Your account is not allowed to manage delegations. Only editors and administrators can.";
+  if (text.includes("not found")) return "That delegation no longer exists.";
+  if (text.includes("only the person who granted")) return "Only the person who granted a delegation, or an administrator, can revoke it.";
+  if (text.includes("network") || text.includes("failed to fetch")) return "Could not reach the server. Check your connection and try again.";
+  const detail = (graphql || raw).trim();
+  return detail ? `The server refused the request: ${detail}` : "Something went wrong. Nothing was changed.";
+}
+
+/** A pending request that an agent started and nobody has approved, denied or let lapse. */
+export function isPendingDelegation(record: CurationDelegationRecord, nowMilliseconds: number): boolean {
+  return record.state === "pending" && Boolean(record.userCode) && Date.parse(record.pendingExpiresAt ?? record.expiresAt) > nowMilliseconds;
+}
+
+/** "9:41 left" for a request that is still open, "Expired" once its window has passed. */
+export function pendingCountdownText(pendingExpiresAt: string | null | undefined, nowMilliseconds: number): string {
+  const remaining = Date.parse(pendingExpiresAt ?? "") - nowMilliseconds;
+  if (!Number.isFinite(remaining) || remaining <= 0) return "Expired";
+  const totalSeconds = Math.ceil(remaining / 1000);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${minutes}:${String(seconds).padStart(2, "0")} left`;
+}
+
+/** The state of a decided or lapsed delegation in words an editor reads in the list. */
+export function delegationStateText(record: CurationDelegationRecord, nowMilliseconds: number): string {
+  if (record.state === "denied") return "Denied";
+  if (record.state === "pending") return pendingCountdownText(record.pendingExpiresAt ?? record.expiresAt, nowMilliseconds) === "Expired" ? "Request expired" : "Waiting for a decision";
+  return delegationExpiryText(record.expiresAt, record.revokedAt, nowMilliseconds);
+}
+
+export function requestedHoursText(hours: number | null | undefined): string {
+  if (!hours || hours <= 0) return "Duration not stated";
+  return `Asks for ${hours} ${hours === 1 ? "hour" : "hours"}`;
+}

package/lib/cyclotron-suggestions.ts

@@ -0,0 +1,263 @@
+import type { MessageRecord } from "./category-repository";
+import type { RelevanceCuration, RelevanceDecisionView } from "./relevance-decisions";
+import { safeId } from "./relevance-status";
+
+export const SHADOW_AGREEMENT_SCHEMA = "cyclotron-shadow-agreement/v1";
+export const MINIMUM_COMPARISONS_FOR_AGREEMENT = 10;
+
+/** What the sweep recorded about the loop itself: whether it is on, when it last ran, why it stopped. */
+export type CyclotronLoopState = {
+  enabled: boolean;
+  stoppedBecause: string | null;
+  lastSweepAt: string | null;
+  maxDecisionsPerDay: number | null;
+};
+
+/** The live-agreement payload the sweep writes: suggestions compared with later human decisions. */
+export type ShadowAgreement = {
+  schema: typeof SHADOW_AGREEMENT_SCHEMA;
+  comparisons: number;
+  agreement: number | null;
+  precision: number | null;
+  recall: number | null;
+  confusion: Record<string, unknown> | null;
+  computedAt: string | null;
+  positiveLabel: string | null;
+  loop: CyclotronLoopState | null;
+};
+
+export type AgreementStripMeasurement = {
+  comparisons: number;
+  agreement: number | null;
+  precision: number | null;
+  recall: number | null;
+  computedAt: string | null;
+};
+
+export type AgreementStripState =
+  | { kind: "hidden" }
+  | {
+    kind: "not_enough" | "measured";
+    measurement: AgreementStripMeasurement;
+    needed: number;
+    loop: CyclotronLoopState | null;
+    stopReasonSentence: string | null;
+  };
+
+export function shadowAgreementPayloadId(cyclotronId: string): string {
+  return `knowledge-raw-payload-cyclotron-shadow-agreement-${safeId(cyclotronId)}`;
+}
+
+function numberOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function parseLoop(value: unknown): CyclotronLoopState | null {
+  if (!value || typeof value !== "object") return null;
+  const loop = value as Record<string, unknown>;
+  if (typeof loop.enabled !== "boolean") return null;
+  return {
+    enabled: loop.enabled,
+    stoppedBecause: typeof loop.stoppedBecause === "string" && loop.stoppedBecause ? loop.stoppedBecause : null,
+    lastSweepAt: typeof loop.lastSweepAt === "string" ? loop.lastSweepAt : null,
+    maxDecisionsPerDay: numberOrNull(loop.maxDecisionsPerDay),
+  };
+}
+
+/** A shadow-agreement payload, or null for any other JSON. */
+export function parseShadowAgreement(json: unknown): ShadowAgreement | null {
+  if (!json || typeof json !== "object") return null;
+  const record = json as Record<string, unknown>;
+  if (record.schema !== SHADOW_AGREEMENT_SCHEMA) return null;
+  return {
+    schema: SHADOW_AGREEMENT_SCHEMA,
+    comparisons: numberOrNull(record.comparisons) ?? 0,
+    agreement: numberOrNull(record.agreement),
+    precision: numberOrNull(record.precision),
+    recall: numberOrNull(record.recall),
+    confusion: record.confusion && typeof record.confusion === "object" ? (record.confusion as Record<string, unknown>) : null,
+    computedAt: typeof record.computedAt === "string" ? record.computedAt : null,
+    positiveLabel: typeof record.positiveLabel === "string" ? record.positiveLabel : null,
+    loop: parseLoop(record.loop),
+  };
+}
+
+/** The newest valid payload among a payload owner's attachments. */
+export function latestShadowAgreement(payloads: Array<{ json: unknown; updatedAt?: string | null }>): ShadowAgreement | null {
+  const valid = payloads
+    .map((payload) => ({ agreement: parseShadowAgreement(payload.json), updatedAt: payload.updatedAt }))
+    .filter((entry): entry is { agreement: ShadowAgreement; updatedAt: string | null | undefined } => entry.agreement !== null)
+    .sort((left, right) => String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")));
+  return valid.length ? valid[0].agreement : null;
+}
+
+const STOP_REASON_WORDS: Record<string, string> = {
+  disabled: "The relevance cyclotron is switched off in the steering config, so it is making no suggestions.",
+  "daily decision cap": "The last sweep stopped at the daily decision cap, so some references have no suggestion yet.",
+};
+
+/** The sentence an editor reads for a stop reason; unknown reasons are shown as given. */
+export function stopReasonSentence(reason: string): string {
+  return STOP_REASON_WORDS[reason] ?? `The last sweep stopped early: ${reason}.`;
+}
+
+/**
+ * What the Live agreement strip shows. No payload hides it; under ten
+ * comparisons the figures are withheld; a stop reason is always put in words.
+ */
+export function agreementStripState(agreement: ShadowAgreement | null): AgreementStripState {
+  if (!agreement) return { kind: "hidden" };
+  const loop = agreement.loop;
+  return {
+    kind: agreement.comparisons < MINIMUM_COMPARISONS_FOR_AGREEMENT ? "not_enough" : "measured",
+    measurement: {
+      comparisons: agreement.comparisons,
+      agreement: agreement.agreement,
+      precision: agreement.precision,
+      recall: agreement.recall,
+      computedAt: agreement.computedAt,
+    },
+    needed: MINIMUM_COMPARISONS_FOR_AGREEMENT,
+    loop,
+    stopReasonSentence: loop?.stoppedBecause ? stopReasonSentence(loop.stoppedBecause) : null,
+  };
+}
+
+/** "Loop on" or "Loop off", the word the strip leads with. */
+export function loopStateWords(loop: CyclotronLoopState): string {
+  return loop.enabled ? "Loop on" : "Loop off";
+}
+
+/** The daily cap in words; no cap is said plainly. */
+export function dailyCapWords(loop: CyclotronLoopState): string {
+  return loop.maxDecisionsPerDay === null ? "No daily decision cap" : `Daily cap ${loop.maxDecisionsPerDay} decisions`;
+}
+
+export function formatPercentage(fraction: number | null): string {
+  return fraction === null ? "not measured" : `${Math.round(fraction * 100)}%`;
+}
+
+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 {};
+  }
+}
+
+/**
+ * Reference lineage ids whose latest curation Message was made by a signed-in
+ * person. Agent and classifier status changes never appear here, and neither
+ * does a reference a person decided before a later non-human change.
+ */
+export function referencesWithHumanLatestCuration(messages: MessageRecord[]): Set<string> {
+  const latestByReference = new Map<string, { createdAt: string; human: boolean }>();
+  for (const message of messages) {
+    if (message.messageKind !== "reference_curation") continue;
+    const metadata = parseMetadata(message.metadata);
+    const lineageId = typeof metadata.referenceLineageId === "string" ? metadata.referenceLineageId : "";
+    if (!lineageId) continue;
+    const seen = latestByReference.get(lineageId);
+    if (seen && seen.createdAt >= message.createdAt) continue;
+    latestByReference.set(lineageId, { createdAt: message.createdAt, human: metadata.actorKind === "human" });
+  }
+  return new Set([...latestByReference].filter(([, entry]) => entry.human).map(([lineageId]) => lineageId));
+}
+
+export type SuggestionChoice = "agree" | "overrule";
+
+/**
+ * The accept or reject an editor's click becomes. Agreeing does what the
+ * suggestion implies; overruling does the opposite. Both are the ordinary
+ * curation actions, tied to the suggestion they answered.
+ */
+export function curationForSuggestionChoice(decision: RelevanceDecisionView, choice: SuggestionChoice): RelevanceCuration {
+  const suggestsAccept = decision.positiveLabel !== null && decision.label === decision.positiveLabel;
+  const accept = choice === "agree" ? suggestsAccept : !suggestsAccept;
+  return {
+    action: accept ? "accept" : "reject",
+    reasonCode: null,
+    note: null,
+    decisionRelationId: decision.decisionRelationId,
+    shareable: false,
+  };
+}
+
+export type ProvenanceSummary = {
+  teachingLabelsSentence: string;
+  primingExamplesSentence: string;
+  doctrineShortHash: string | null;
+  modelVersion: string | null;
+  decidedAt: string | null;
+};
+
+const SHORT_HASH_LENGTH = 8;
+
+/** The facts the "How this suggestion was made" block lists; null when the decision recorded no provenance. */
+export function provenanceSummary(decision: RelevanceDecisionView): ProvenanceSummary | null {
+  const provenance = decision.provenance;
+  if (!provenance) return null;
+  const plural = (count: number, singular: string) => `${count} ${singular}${count === 1 ? "" : "s"}`;
+  return {
+    teachingLabelsSentence: `Taught by ${plural(provenance.teachingLabels, "label")} that editors set themselves`,
+    primingExamplesSentence: `${plural(provenance.primingExamples, "priming example")} supplied as starting examples`,
+    doctrineShortHash: provenance.doctrineFingerprint ? provenance.doctrineFingerprint.slice(0, SHORT_HASH_LENGTH) : null,
+    modelVersion: decision.version === null ? null : `version ${decision.version}`,
+    decidedAt: decision.decidedAt,
+  };
+}
+
+export function suggestionConfidenceWords(decision: RelevanceDecisionView): string {
+  return decision.confidence === null ? "confidence unknown" : `${Math.round(decision.confidence * 100)}% sure`;
+}
+
+/** A curation recorded by an agent using a delegation a person granted. */
+export type DelegatedCuration = {
+  agent: string;
+  person: string | null;
+  instruction: string;
+  delegationId: string;
+  delegationShortId: string;
+  /** What the backend does: a delegated curation is stamped human, so the person's label trains the cyclotron. */
+  countsAsTrainingLabel: boolean;
+};
+
+const DELEGATION_ID_PREFIX = "curation-delegation-";
+const DELEGATION_SHORT_ID_LENGTH = 8;
+
+export function delegationShortId(delegationId: string): string {
+  return delegationId.replace(DELEGATION_ID_PREFIX, "").slice(0, DELEGATION_SHORT_ID_LENGTH);
+}
+
+/**
+ * Delegated curations by reference lineage, from each reference's latest
+ * curation Message only. The person is the Message author; the agent is relayedBy.
+ */
+export function delegatedCurationsByReference(messages: MessageRecord[]): Map<string, DelegatedCuration> {
+  const latest = new Map<string, MessageRecord>();
+  for (const message of messages) {
+    if (message.messageKind !== "reference_curation") continue;
+    const lineageId = parseMetadata(message.metadata).referenceLineageId;
+    if (typeof lineageId !== "string" || !lineageId) continue;
+    const seen = latest.get(lineageId);
+    if (!seen || seen.createdAt < message.createdAt) latest.set(lineageId, message);
+  }
+  const delegated = new Map<string, DelegatedCuration>();
+  for (const [lineageId, message] of latest) {
+    const metadata = parseMetadata(message.metadata);
+    if (metadata.attestation !== "delegated") continue;
+    const delegationId = typeof metadata.delegationId === "string" ? metadata.delegationId : "";
+    delegated.set(lineageId, {
+      agent: typeof metadata.relayedBy === "string" && metadata.relayedBy ? metadata.relayedBy : "an agent",
+      person: message.authorLabel?.trim() || null,
+      instruction: typeof metadata.instruction === "string" ? metadata.instruction : "",
+      delegationId,
+      delegationShortId: delegationShortId(delegationId),
+      countsAsTrainingLabel: metadata.actorKind === "human",
+    });
+  }
+  return delegated;
+}

package/lib/front-matter-fields.ts

@@ -0,0 +1,42 @@
+import { parseDocument } from "yaml";
+import type { ContentItemVersionRecord } from "./content-item-lifecycle";
+
+/** Front matter keys the editor shows as form fields instead of raw YAML. */
+export const FRONT_MATTER_TITLE_KEY = "title";
+export const FRONT_MATTER_SUBTITLE_KEY = "deck";
+export const FRONT_MATTER_BLURB_KEY = "blurb";
+
+/** Reads one text field from front matter YAML; invalid YAML or a non-text value reads as empty. */
+export function readFrontMatterText(frontMatterYaml: string | null | undefined, key: string): string {
+  if (!frontMatterYaml?.trim()) return "";
+  const document = parseDocument(frontMatterYaml);
+  if (document.errors.length) return "";
+  const value = document.get(key);
+  return typeof value === "string" ? value : "";
+}
+
+/** Sets or removes one text field in front matter YAML, keeping every other line and comment as written. */
+export function writeFrontMatterText(frontMatterYaml: string | null | undefined, key: string, value: string): string {
+  const document = parseDocument(frontMatterYaml?.trim() ? frontMatterYaml : "{}\n");
+  if (document.errors.length) return frontMatterYaml ?? "";
+  if (value.trim()) document.set(key, value);
+  else document.delete(key);
+  const text = document.toString();
+  return text.trim() === "{}" ? "" : text;
+}
+
+function metadataFrontMatterYaml(metadata: unknown): string {
+  const parsed = typeof metadata === "string" ? safeJson(metadata) : metadata;
+  const text = (parsed as { frontMatterYaml?: unknown } | null)?.frontMatterYaml;
+  return typeof text === "string" ? text : "";
+}
+
+function safeJson(text: string): unknown {
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+/** A few lines for a board card: the blurb when one is recorded, else the subtitle. */
+export function contentItemExcerpt(version: Pick<ContentItemVersionRecord, "deck" | "metadata">): string | undefined {
+  const blurb = readFrontMatterText(metadataFrontMatterYaml(version.metadata), FRONT_MATTER_BLURB_KEY).trim();
+  return blurb || version.deck?.trim() || undefined;
+}