feat: read and validate curated FK annotations at the pinned commit (P5)

backend/src/workspaces/annotations.ts

@@ -0,0 +1,28 @@
+import { parseAllDocuments } from "yaml";
+import { WorkspaceRegistryError } from "./git-repository.js";
+
+/**
+ * Coarse structural validation for a curated annotation blob at activation time. The harness
+ * Pydantic parser remains the authority for per-table shapes; this check rejects only YAML that
+ * cannot possibly be a canonical `Annotations` document (single mapping, optional `tables` mapping).
+ */
+export function parseAnnotationsYaml(source: string): void {
+  try {
+    const documents = parseAllDocuments(source, { uniqueKeys: true });
+    if (documents.length !== 1) throw new Error("malformed annotations");
+    const document = documents[0];
+    if (document.errors.length > 0 || document.warnings.length > 0) throw new Error("malformed annotations");
+    const parsed = document.toJSON();
+    if (parsed === null || parsed === undefined) return; // empty canonical set
+    if (typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("malformed annotations");
+    const record = parsed as Record<string, unknown>;
+    if (
+      record.tables !== undefined
+      && (typeof record.tables !== "object" || record.tables === null || Array.isArray(record.tables))
+    ) {
+      throw new Error("malformed annotations");
+    }
+  } catch {
+    throw new WorkspaceRegistryError("workspace_invalid", "Workspace annotations are malformed");
+  }
+}