coaia-visualizer 1.6.4 → 1.6.6

package/lib/asterion-metadata.ts

@@ -0,0 +1,704 @@
+import type {
+  ArtifactDiffEntry,
+  Chart,
+  EntityRecord,
+  FoundationMetadata,
+  FoundationProjection,
+  MetadataWarning,
+  ParsedIssueReference,
+  SessionContextMetadata,
+  SessionContextProjection,
+  SessionLineageBranchProjection,
+  SessionLineageGroupProjection,
+  SessionLineageMetadata,
+  SessionLineageProjection,
+} from "./types.ts"
+
+const FOUNDATION_KEYS: Array<keyof FoundationMetadata> = [
+  "packetRoot",
+  "foundationType",
+  "parentIssue",
+  "baselineIssue",
+  "inquiryIssue",
+  "protocolIssue",
+  "schemaIssue",
+  "visualizerIssue",
+  "expectedArtifacts",
+  "producedArtifacts",
+  "evaluationStatus",
+  "privacyClass",
+  "publicationStatus",
+  "commitHandles",
+]
+
+const FOUNDATION_REQUIRED_FIELDS: Array<keyof FoundationMetadata> = [
+  "packetRoot",
+  "foundationType",
+  "parentIssue",
+  "baselineIssue",
+  "inquiryIssue",
+  "protocolIssue",
+  "schemaIssue",
+  "visualizerIssue",
+  "expectedArtifacts",
+  "evaluationStatus",
+  "privacyClass",
+  "publicationStatus",
+]
+
+const SESSION_LINEAGE_KEYS: Array<keyof SessionLineageMetadata> = [
+  "platform",
+  "parentChartId",
+  "sourceBeat",
+  "originalSessionId",
+  "branchSessionId",
+  "branchIndex",
+  "copiedMessageCount",
+  "branchPurpose",
+  "relatedIssues",
+  "handoffState",
+]
+
+const SESSION_LINEAGE_REQUIRED_FIELDS: Array<keyof SessionLineageMetadata> = [
+  "platform",
+  "parentChartId",
+  "sourceBeat",
+  "originalSessionId",
+  "branchSessionId",
+  "branchIndex",
+  "copiedMessageCount",
+  "branchPurpose",
+  "handoffState",
+]
+
+const SESSION_CONTEXT_KEYS: Array<keyof SessionContextMetadata> = [
+  "mode",
+  "setting",
+  "captureQuality",
+  "continuationKind",
+  "privateChroniclePath",
+  "handle",
+  "publicSummaryAllowed",
+  "landBasedLearning",
+  "environmentNotes",
+  "listeningContext",
+]
+
+const SESSION_CONTEXT_REQUIRED_FIELDS: Array<keyof SessionContextMetadata> = [
+  "mode",
+  "setting",
+  "captureQuality",
+  "continuationKind",
+  "publicSummaryAllowed",
+]
+
+const FOUNDATION_EVALUATION_STATUSES = ["expected", "delegated", "produced", "evaluated"] as const
+const FOUNDATION_PRIVACY_CLASSES = ["public-safe", "private", "mixed"] as const
+const FOUNDATION_PUBLICATION_STATUSES = ["planned", "draft", "reviewed", "published"] as const
+const SESSION_HANDOFF_STATES = [
+  "requirements-created",
+  "implementation-ready",
+  "returned-to-parent",
+] as const
+
+const SESSION_CAPTURE_QUALITIES = ["complete", "partial", "noisy", "transcript-only", "clear", "windy"] as const
+const SESSION_CONTINUATION_KINDS = ["new", "resumption", "branch-return", "daily-chronicle", "branch", "parent-return", "follow-up"] as const
+
+function isObject(value: unknown): value is Record<string, any> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function asTrimmedString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined
+  const trimmed = value.trim()
+  return trimmed ? trimmed : undefined
+}
+
+function normalizeList(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value
+      .map((item) => asTrimmedString(typeof item === "string" ? item : JSON.stringify(item)))
+      .filter((item): item is string => Boolean(item))
+  }
+
+  if (typeof value === "string") {
+    return value
+      .split(/[\n,]/)
+      .map((item) => item.trim())
+      .filter(Boolean)
+  }
+
+  return []
+}
+
+function asNumber(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value)
+    return Number.isFinite(parsed) ? parsed : undefined
+  }
+  return undefined
+}
+
+function hasAnyValue(record: Record<string, any>, keys: readonly string[]): boolean {
+  return keys.some((key) => record[key] !== undefined && record[key] !== null && record[key] !== "")
+}
+
+function toLookupKey(value: string): string {
+  return value.trim().toLowerCase()
+}
+
+function slugify(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "beat"
+}
+
+function pushPayloadCandidate(candidates: Record<string, any>[], candidate: unknown, keys: readonly string[]): void {
+  if (isObject(candidate) && hasAnyValue(candidate, keys)) {
+    candidates.push(candidate)
+  }
+}
+
+function foundationPayloads(metadata: Record<string, any>): Record<string, any>[] {
+  const candidates: Record<string, any>[] = []
+  pushPayloadCandidate(candidates, metadata.asterion?.foundation, FOUNDATION_KEYS)
+  pushPayloadCandidate(candidates, metadata.asterionFoundation, FOUNDATION_KEYS)
+  pushPayloadCandidate(candidates, metadata.foundationMetadata, FOUNDATION_KEYS)
+  pushPayloadCandidate(candidates, metadata.foundation, FOUNDATION_KEYS)
+  pushPayloadCandidate(candidates, metadata.asterionMetadata?.foundation, FOUNDATION_KEYS)
+  pushPayloadCandidate(candidates, metadata.asterion, FOUNDATION_KEYS)
+  pushPayloadCandidate(candidates, metadata, FOUNDATION_KEYS)
+  return candidates
+}
+
+function lineagePayloads(metadata: Record<string, any>): Record<string, any>[] {
+  const candidates: Record<string, any>[] = []
+  pushPayloadCandidate(candidates, metadata.asterion?.sessionLineage, SESSION_LINEAGE_KEYS)
+  pushPayloadCandidate(candidates, metadata.sessionLineageMetadata, SESSION_LINEAGE_KEYS)
+  pushPayloadCandidate(candidates, metadata.sessionLineage, SESSION_LINEAGE_KEYS)
+  pushPayloadCandidate(candidates, metadata.asterionMetadata?.sessionLineage, SESSION_LINEAGE_KEYS)
+  pushPayloadCandidate(candidates, metadata.asterion, SESSION_LINEAGE_KEYS)
+  pushPayloadCandidate(candidates, metadata, SESSION_LINEAGE_KEYS)
+  return candidates
+}
+
+function sessionContextPayloads(metadata: Record<string, any>): Record<string, any>[] {
+  const candidates: Record<string, any>[] = []
+  pushPayloadCandidate(candidates, metadata.asterion?.sessionContext, SESSION_CONTEXT_KEYS)
+  pushPayloadCandidate(candidates, metadata.sessionContextMetadata, SESSION_CONTEXT_KEYS)
+  pushPayloadCandidate(candidates, metadata.sessionContext, SESSION_CONTEXT_KEYS)
+  pushPayloadCandidate(candidates, metadata.asterionMetadata?.sessionContext, SESSION_CONTEXT_KEYS)
+  pushPayloadCandidate(candidates, metadata.livedContext, SESSION_CONTEXT_KEYS)
+  pushPayloadCandidate(candidates, metadata.asterion, SESSION_CONTEXT_KEYS)
+  pushPayloadCandidate(candidates, metadata, SESSION_CONTEXT_KEYS)
+  return candidates
+}
+
+function buildWarning(message: string, record?: Pick<EntityRecord, "name" | "entityType">): MetadataWarning {
+  return {
+    severity: "warning",
+    recordName: record?.name,
+    recordType: record?.entityType,
+    message,
+  }
+}
+
+function dedupeWarnings(warnings: MetadataWarning[]): MetadataWarning[] {
+  const seen = new Set<string>()
+  return warnings.filter((warning) => {
+    const key = `${warning.recordName || ""}|${warning.recordType || ""}|${warning.message}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
+function normalizeFoundationPayload(payload: Record<string, any>, record?: EntityRecord): {
+  foundation: Partial<FoundationMetadata>
+  warnings: MetadataWarning[]
+} {
+  const warnings: MetadataWarning[] = []
+  const foundation: Partial<FoundationMetadata> = {}
+
+  foundation.packetRoot = asTrimmedString(payload.packetRoot)
+  foundation.foundationType = asTrimmedString(payload.foundationType)
+  foundation.parentIssue = asTrimmedString(payload.parentIssue)
+  foundation.baselineIssue = asTrimmedString(payload.baselineIssue)
+  foundation.inquiryIssue = asTrimmedString(payload.inquiryIssue)
+  foundation.protocolIssue = asTrimmedString(payload.protocolIssue)
+  foundation.schemaIssue = asTrimmedString(payload.schemaIssue)
+  foundation.visualizerIssue = asTrimmedString(payload.visualizerIssue)
+
+  if (payload.expectedArtifacts !== undefined) {
+    foundation.expectedArtifacts = normalizeList(payload.expectedArtifacts)
+  }
+  if (payload.producedArtifacts !== undefined) {
+    foundation.producedArtifacts = normalizeList(payload.producedArtifacts)
+  }
+  if (payload.commitHandles !== undefined) {
+    foundation.commitHandles = normalizeList(payload.commitHandles)
+  }
+
+  const evaluationStatus = asTrimmedString(payload.evaluationStatus)
+  if (evaluationStatus) {
+    if (FOUNDATION_EVALUATION_STATUSES.includes(evaluationStatus as (typeof FOUNDATION_EVALUATION_STATUSES)[number])) {
+      foundation.evaluationStatus = evaluationStatus as FoundationMetadata["evaluationStatus"]
+    } else {
+      warnings.push(buildWarning(`Foundation evaluationStatus \"${evaluationStatus}\" is not recognized.`, record))
+    }
+  }
+
+  const privacyClass = asTrimmedString(payload.privacyClass)
+  if (privacyClass) {
+    if (FOUNDATION_PRIVACY_CLASSES.includes(privacyClass as (typeof FOUNDATION_PRIVACY_CLASSES)[number])) {
+      foundation.privacyClass = privacyClass as FoundationMetadata["privacyClass"]
+    } else {
+      warnings.push(buildWarning(`Foundation privacyClass \"${privacyClass}\" is not recognized.`, record))
+    }
+  }
+
+  const publicationStatus = asTrimmedString(payload.publicationStatus)
+  if (publicationStatus) {
+    if (FOUNDATION_PUBLICATION_STATUSES.includes(publicationStatus as (typeof FOUNDATION_PUBLICATION_STATUSES)[number])) {
+      foundation.publicationStatus = publicationStatus as FoundationMetadata["publicationStatus"]
+    } else {
+      warnings.push(buildWarning(`Foundation publicationStatus \"${publicationStatus}\" is not recognized.`, record))
+    }
+  }
+
+  return {
+    foundation: Object.fromEntries(Object.entries(foundation).filter(([, value]) => value !== undefined)) as Partial<FoundationMetadata>,
+    warnings,
+  }
+}
+
+function normalizeSessionLineagePayload(payload: Record<string, any>, record?: EntityRecord): {
+  lineage: Partial<SessionLineageMetadata>
+  warnings: MetadataWarning[]
+} {
+  const warnings: MetadataWarning[] = []
+  const lineage: Partial<SessionLineageMetadata> = {}
+
+  lineage.platform = asTrimmedString(payload.platform)
+  lineage.parentChartId = asTrimmedString(payload.parentChartId)
+  lineage.sourceBeat = asTrimmedString(payload.sourceBeat)
+  lineage.originalSessionId = asTrimmedString(payload.originalSessionId)
+  lineage.branchSessionId = asTrimmedString(payload.branchSessionId)
+  lineage.branchIndex = asNumber(payload.branchIndex)
+  lineage.copiedMessageCount = asNumber(payload.copiedMessageCount)
+  lineage.branchPurpose = asTrimmedString(payload.branchPurpose)
+
+  if (payload.relatedIssues !== undefined) {
+    lineage.relatedIssues = normalizeList(payload.relatedIssues)
+  }
+
+  const handoffState = asTrimmedString(payload.handoffState)
+  if (handoffState) {
+    if (SESSION_HANDOFF_STATES.includes(handoffState as (typeof SESSION_HANDOFF_STATES)[number])) {
+      lineage.handoffState = handoffState as SessionLineageMetadata["handoffState"]
+    } else {
+      warnings.push(buildWarning(`Session lineage handoffState \"${handoffState}\" is not recognized.`, record))
+    }
+  }
+
+  return {
+    lineage: Object.fromEntries(Object.entries(lineage).filter(([, value]) => value !== undefined)) as Partial<SessionLineageMetadata>,
+    warnings,
+  }
+}
+
+function normalizeSessionContextPayload(payload: Record<string, any>, record?: EntityRecord): {
+  context: Partial<SessionContextMetadata>
+  warnings: MetadataWarning[]
+} {
+  const warnings: MetadataWarning[] = []
+  const context: Partial<SessionContextMetadata> = {}
+
+  context.mode = asTrimmedString(payload.mode)
+  context.setting = asTrimmedString(payload.setting)
+  context.privateChroniclePath = asTrimmedString(payload.privateChroniclePath)
+  context.handle = asTrimmedString(payload.handle)
+
+  const publicSummaryAllowed = payload.publicSummaryAllowed
+  if (typeof publicSummaryAllowed === "boolean") {
+    context.publicSummaryAllowed = publicSummaryAllowed
+  } else if (typeof publicSummaryAllowed === "string") {
+    const normalized = publicSummaryAllowed.toLowerCase().trim()
+    if (normalized === "true" || normalized === "yes") {
+      context.publicSummaryAllowed = true
+    } else if (normalized === "false" || normalized === "no") {
+      context.publicSummaryAllowed = false
+    }
+  }
+
+  const captureQuality = asTrimmedString(payload.captureQuality)
+  if (captureQuality) {
+    if (SESSION_CAPTURE_QUALITIES.includes(captureQuality as (typeof SESSION_CAPTURE_QUALITIES)[number])) {
+      context.captureQuality = captureQuality as SessionContextMetadata["captureQuality"]
+    } else {
+      warnings.push(buildWarning(`Session context captureQuality "${captureQuality}" is not recognized.`, record))
+    }
+  }
+
+  const continuationKind = asTrimmedString(payload.continuationKind)
+  if (continuationKind) {
+    if (SESSION_CONTINUATION_KINDS.includes(continuationKind as (typeof SESSION_CONTINUATION_KINDS)[number])) {
+      context.continuationKind = continuationKind as SessionContextMetadata["continuationKind"]
+    } else {
+      warnings.push(buildWarning(`Session context continuationKind "${continuationKind}" is not recognized.`, record))
+    }
+  }
+
+  const landBasedLearning = payload.landBasedLearning
+  if (typeof landBasedLearning === "boolean") {
+    context.landBasedLearning = landBasedLearning
+  } else if (typeof landBasedLearning === "string") {
+    const normalizedLand = landBasedLearning.toLowerCase().trim()
+    if (normalizedLand === "true" || normalizedLand === "yes") {
+      context.landBasedLearning = true
+    } else if (normalizedLand === "false" || normalizedLand === "no") {
+      context.landBasedLearning = false
+    }
+  }
+
+  const environmentNotes = payload.environmentNotes
+  if (Array.isArray(environmentNotes)) {
+    const notes = environmentNotes.filter((n): n is string => typeof n === "string" && n.trim().length > 0)
+    if (notes.length > 0) {
+      context.environmentNotes = notes
+    }
+  } else if (typeof environmentNotes === "string" && environmentNotes.trim().length > 0) {
+    context.environmentNotes = [environmentNotes.trim()]
+  }
+
+  const listeningContextValue = asTrimmedString(payload.listeningContext)
+  if (listeningContextValue) {
+    context.listeningContext = listeningContextValue
+  }
+
+  return {
+    context: Object.fromEntries(Object.entries(context).filter(([, value]) => value !== undefined)) as Partial<SessionContextMetadata>,
+    warnings,
+  }
+}
+
+function parseIssueReference(value: string, key: string): ParsedIssueReference {
+  const raw = value.trim()
+  const urlMatch = raw.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+)\/(issues|pull)\/(\d+)/i)
+  if (urlMatch) {
+    const [, owner, repo, , number] = urlMatch
+    return {
+      key,
+      raw,
+      label: `${owner}/${repo}#${number}`,
+      href: raw,
+      owner,
+      repo,
+      number: Number(number),
+    }
+  }
+
+  const repoMatch = raw.match(/^([^/\s]+)\/([^#\s]+)#(\d+)$/)
+  if (repoMatch) {
+    const [, owner, repo, number] = repoMatch
+    return {
+      key,
+      raw,
+      label: `${owner}/${repo}#${number}`,
+      href: `https://github.com/${owner}/${repo}/issues/${number}`,
+      owner,
+      repo,
+      number: Number(number),
+    }
+  }
+
+  const shortMatch = raw.match(/^#?(\d+)$/)
+  if (shortMatch) {
+    const [, number] = shortMatch
+    return {
+      key,
+      raw,
+      label: `#${number}`,
+      number: Number(number),
+    }
+  }
+
+  return {
+    key,
+    raw,
+    label: raw,
+  }
+}
+
+export function getNarrativeBeatAnchorId(beat: Pick<EntityRecord, "name" | "metadata">, index = 0): string {
+  const seed =
+    asTrimmedString(beat.metadata?.beatId) ||
+    asTrimmedString(beat.metadata?.sourceBeat) ||
+    asTrimmedString(beat.metadata?.beatKey) ||
+    beat.name ||
+    `beat-${index + 1}`
+
+  return `beat-${slugify(seed)}`
+}
+
+function buildBeatAnchorLookup(beats: EntityRecord[]): Map<string, string> {
+  const lookup = new Map<string, string>()
+
+  beats.forEach((beat, index) => {
+    const anchor = getNarrativeBeatAnchorId(beat, index)
+    const candidates = [
+      beat.name,
+      asTrimmedString(beat.metadata?.beatId),
+      asTrimmedString(beat.metadata?.sourceBeat),
+      asTrimmedString(beat.metadata?.beatKey),
+      asTrimmedString(beat.observations?.[0]),
+      anchor.replace(/^beat-/, ""),
+    ].filter((value): value is string => Boolean(value))
+
+    for (const candidate of candidates) {
+      lookup.set(toLookupKey(candidate), anchor)
+      lookup.set(slugify(candidate), anchor)
+    }
+  })
+
+  return lookup
+}
+
+function buildFoundationIssueRefs(foundation: Partial<FoundationMetadata>): ParsedIssueReference[] {
+  const issueFields: Array<keyof Pick<
+    FoundationMetadata,
+    "parentIssue" | "baselineIssue" | "inquiryIssue" | "protocolIssue" | "schemaIssue" | "visualizerIssue"
+  >> = ["parentIssue", "baselineIssue", "inquiryIssue", "protocolIssue", "schemaIssue", "visualizerIssue"]
+
+  return issueFields
+    .map((field) => foundation[field] ? parseIssueReference(foundation[field]!, field) : undefined)
+    .filter((value): value is ParsedIssueReference => Boolean(value))
+}
+
+export function parseFoundationMetadata(records: EntityRecord[]): FoundationProjection | undefined {
+  const foundation: Partial<FoundationMetadata> = {}
+  const warnings: MetadataWarning[] = []
+  const sourceRecords = new Set<string>()
+  let foundFoundationMetadata = false
+
+  for (const record of records) {
+    if (!isObject(record.metadata)) continue
+
+    for (const payload of foundationPayloads(record.metadata)) {
+      foundFoundationMetadata = true
+      sourceRecords.add(record.name)
+      const normalized = normalizeFoundationPayload(payload, record)
+      warnings.push(...normalized.warnings)
+
+      for (const [key, value] of Object.entries(normalized.foundation) as Array<[keyof FoundationMetadata, FoundationMetadata[keyof FoundationMetadata]]>) {
+        if (foundation[key] === undefined) {
+          ;(foundation as Record<string, unknown>)[key] = value
+        }
+      }
+    }
+  }
+
+  if (!foundFoundationMetadata) {
+    return undefined
+  }
+
+  for (const field of FOUNDATION_REQUIRED_FIELDS) {
+    const value = foundation[field]
+    const isMissing = value === undefined || (Array.isArray(value) && value.length === 0)
+    if (isMissing) {
+      warnings.push(buildWarning(`Foundation metadata is missing required field \"${field}\".`))
+    }
+  }
+
+  const artifactDiff = Array.from(
+    new Set([...(foundation.expectedArtifacts || []), ...(foundation.producedArtifacts || [])]),
+  )
+    .sort((left, right) => left.localeCompare(right))
+    .map((artifact): ArtifactDiffEntry => ({
+      artifact,
+      expected: (foundation.expectedArtifacts || []).includes(artifact),
+      produced: (foundation.producedArtifacts || []).includes(artifact),
+      status: (foundation.expectedArtifacts || []).includes(artifact)
+        ? (foundation.producedArtifacts || []).includes(artifact)
+          ? "matched"
+          : "missing"
+        : "unexpected",
+    }))
+
+  for (const artifact of artifactDiff) {
+    if (artifact.status === "missing") {
+      warnings.push(buildWarning(`Expected artifact \"${artifact.artifact}\" has not been produced yet.`))
+    }
+    if (artifact.status === "unexpected") {
+      warnings.push(buildWarning(`Produced artifact \"${artifact.artifact}\" is not listed in expectedArtifacts.`))
+    }
+  }
+
+  return {
+    foundation,
+    warnings: dedupeWarnings(warnings),
+    issueRefs: buildFoundationIssueRefs(foundation),
+    artifactDiff,
+    sourceRecords: Array.from(sourceRecords),
+  }
+}
+
+export function parseSessionLineageMetadata(
+  records: EntityRecord[],
+  beats: EntityRecord[] = [],
+): SessionLineageProjection | undefined {
+  const beatAnchors = buildBeatAnchorLookup(beats)
+  const branches: SessionLineageBranchProjection[] = []
+
+  for (const record of records) {
+    if (!isObject(record.metadata)) continue
+
+    for (const payload of lineagePayloads(record.metadata)) {
+      const normalized = normalizeSessionLineagePayload(payload, record)
+      if (Object.keys(normalized.lineage).length === 0 && normalized.warnings.length === 0) {
+        continue
+      }
+
+      const entryWarnings = [...normalized.warnings]
+      for (const field of SESSION_LINEAGE_REQUIRED_FIELDS) {
+        const value = normalized.lineage[field]
+        const isMissing = value === undefined || (Array.isArray(value) && value.length === 0)
+        if (isMissing) {
+          entryWarnings.push(buildWarning(`Session lineage metadata is missing required field \"${field}\".`, record))
+        }
+      }
+
+      const sourceBeat = normalized.lineage.sourceBeat
+      const sourceBeatAnchor = sourceBeat
+        ? beatAnchors.get(toLookupKey(sourceBeat)) || beatAnchors.get(slugify(sourceBeat))
+        : undefined
+
+      branches.push({
+        metadata: normalized.lineage,
+        sourceRecordName: record.name,
+        sourceRecordType: record.entityType,
+        warnings: dedupeWarnings(entryWarnings),
+        relatedIssueRefs: (normalized.lineage.relatedIssues || []).map((issue, index) =>
+          parseIssueReference(issue, `relatedIssues.${index}`),
+        ),
+        sourceBeatAnchor,
+        sourceBeatExistsInChart: Boolean(sourceBeatAnchor),
+      })
+    }
+  }
+
+  if (branches.length === 0) {
+    return undefined
+  }
+
+  branches.sort((left, right) => {
+    const sourceBeatCompare = (left.metadata.sourceBeat || "").localeCompare(right.metadata.sourceBeat || "")
+    if (sourceBeatCompare !== 0) return sourceBeatCompare
+
+    const indexCompare = (left.metadata.branchIndex ?? Number.MAX_SAFE_INTEGER) - (right.metadata.branchIndex ?? Number.MAX_SAFE_INTEGER)
+    if (indexCompare !== 0) return indexCompare
+
+    return (left.sourceRecordName || "").localeCompare(right.sourceRecordName || "")
+  })
+
+  const grouped = new Map<string, SessionLineageGroupProjection>()
+  for (const branch of branches) {
+    const sourceBeat = branch.metadata.sourceBeat || "Unassigned source beat"
+    const existing = grouped.get(sourceBeat)
+    if (existing) {
+      existing.branches.push(branch)
+      continue
+    }
+
+    grouped.set(sourceBeat, {
+      sourceBeat,
+      sourceBeatAnchor: branch.sourceBeatAnchor,
+      sourceBeatExistsInChart: branch.sourceBeatExistsInChart,
+      branches: [branch],
+    })
+  }
+
+  return {
+    branches,
+    groupedBranches: Array.from(grouped.values()),
+    warnings: dedupeWarnings(branches.flatMap((branch) => branch.warnings)),
+  }
+}
+
+export function parseSessionContextMetadata(beat: EntityRecord, beatIndex: number): SessionContextProjection | undefined {
+  if (!isObject(beat.metadata)) return undefined
+
+  let context: Partial<SessionContextMetadata> = {}
+  let warnings: MetadataWarning[] = []
+  let foundSessionContext = false
+
+  for (const payload of sessionContextPayloads(beat.metadata)) {
+    foundSessionContext = true
+    const normalized = normalizeSessionContextPayload(payload, beat)
+    warnings.push(...normalized.warnings)
+
+    for (const [key, value] of Object.entries(normalized.context) as Array<[keyof SessionContextMetadata, SessionContextMetadata[keyof SessionContextMetadata]]>) {
+      if (context[key] === undefined) {
+        ;(context as Record<string, unknown>)[key] = value
+      }
+    }
+  }
+
+  if (!foundSessionContext) {
+    return undefined
+  }
+
+  for (const field of SESSION_CONTEXT_REQUIRED_FIELDS) {
+    const value = context[field]
+    const isMissing = value === undefined || (Array.isArray(value) && value.length === 0)
+    if (isMissing) {
+      warnings.push(buildWarning(`Session context is missing required field "${field}".`, beat))
+    }
+  }
+
+  if (context.captureQuality === "partial" || context.captureQuality === "noisy") {
+    warnings.push({
+      severity: "warning",
+      recordName: beat.name,
+      recordType: beat.entityType,
+      message: `Capture quality is "${context.captureQuality}" - record may be incomplete or contain transcription errors.`,
+    })
+  }
+
+  if (context.privateChroniclePath && !context.handle) {
+    warnings.push({
+      severity: "warning",
+      recordName: beat.name,
+      recordType: beat.entityType,
+      message: "privateChroniclePath is present but no handle is specified - Chronicle reference may not be navigable.",
+    })
+  }
+
+  return {
+    context,
+    warnings: dedupeWarnings(warnings),
+    beatName: beat.name,
+    beatIndex,
+  }
+}
+
+function getAsterionSourceRecords(chart: Chart): EntityRecord[] {
+  return [
+    chart.chartEntity,
+    ...chart.actions,
+    ...chart.narrativeBeats,
+    chart.desiredOutcome,
+    chart.currentReality,
+  ].filter((record): record is EntityRecord => Boolean(record))
+}
+
+export function extractAsterionMetadata(chart: Chart): Pick<Chart, "foundationProjection" | "sessionLineageProjection"> {
+  const records = getAsterionSourceRecords(chart)
+  return {
+    foundationProjection: parseFoundationMetadata(records),
+    sessionLineageProjection: parseSessionLineageMetadata(records, chart.narrativeBeats),
+  }
+}