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");
+  }
+}

backend/src/workspaces/git-repository.ts

@@ -2,7 +2,7 @@ import { execFile, spawn, type ChildProcessWithoutNullStreams } from "node:child
 import { lstatSync, mkdirSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join } from "node:path";
-import { promisify } from "node:util";
+import { promisify, TextDecoder } from "node:util";
 import type { WorkspaceErrorCode, WorkspaceRegistryConfig } from "./types.js";
 
 const execFileAsync = promisify(execFile);
@@ -39,6 +39,15 @@ function assertDirectory(path: string): void {
   }
 }
 
+function isValidUtf8(buffer: Buffer): boolean {
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function gitErrorCode(error: unknown): WorkspaceErrorCode {
   const detail = [
     error instanceof Error ? error.message : "",
@@ -233,6 +242,66 @@ export class GitWorkspaceRepository {
     }
   }
 
+  /** Read the curated FK annotations object at an exact commit, or undefined when absent. */
+  async annotationsObject(revision: string, id: string): Promise<{ blobId: string; contents: Buffer } | undefined> {
+    if (!/^[0-9a-f]{40}$/.test(revision)) {
+      throw new WorkspaceRegistryError("workspace_invalid", "Workspace annotations revision is invalid");
+    }
+    if (!/^[a-z][a-z0-9-]{2,62}$/.test(id) || id === "workspace-docs") {
+      throw new WorkspaceRegistryError("workspace_invalid", "Workspace annotations path is invalid");
+    }
+    const path = `${id}/schema/annotations.yaml`;
+    // ls-tree -z reports the exact object at the path (or its children when the path is a tree).
+    const listing = await this.git(["ls-tree", "-z", "--full-tree", revision, "--", path]);
+    const entries = listing.split("\0").filter((entry) => entry.length > 0);
+    if (entries.length === 0) return undefined;
+    const exact = entries.find((entry) => entry.slice(entry.lastIndexOf("\t") + 1) === path);
+    if (exact === undefined) {
+      // The path resolves to a tree (its children are listed) or another non-blob object.
+      throw new WorkspaceRegistryError("workspace_invalid", "Workspace annotations object is invalid");
+    }
+    const match = /^([0-9]{6})\s+(blob|tree|commit)\s+([0-9a-f]{40})\t/.exec(exact);
+    // Only regular Git blobs are accepted: symlinks (120000) and gitlinks (160000) are refused.
+    if (match === null || match[2] !== "blob" || (match[1] !== "100644" && match[1] !== "100755")) {
+      throw new WorkspaceRegistryError("workspace_invalid", "Workspace annotations object is invalid");
+    }
+    const blobId = match[3];
+    const contents = await this.gitBlobBuffer(blobId, 16 * 1024 * 1024);
+    if (!isValidUtf8(contents)) {
+      throw new WorkspaceRegistryError("workspace_invalid", "Workspace annotations object is not valid UTF-8");
+    }
+    return { blobId, contents };
+  }
+
+  private async gitBlobBuffer(objectId: string, maxBytes: number): Promise<Buffer> {
+    if (!/^[0-9a-f]{40}$/.test(objectId)) {
+      throw new WorkspaceRegistryError("workspace_invalid", "Workspace annotations object is invalid");
+    }
+    try {
+      const { stdout } = await execFileAsync(
+        "git",
+        ["-c", `core.hooksPath=${this.hooksPath}`, "cat-file", "blob", objectId],
+        {
+          cwd: this.repoPath,
+          env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+          encoding: "buffer",
+          maxBuffer: maxBytes + 1024 * 1024,
+        },
+      );
+      if (stdout.length > maxBytes) {
+        throw new WorkspaceRegistryError("workspace_invalid", "Workspace annotations object is too large");
+      }
+      return stdout;
+    } catch (error) {
+      if (error instanceof WorkspaceRegistryError) throw error;
+      const detail = error instanceof Error ? error.message : "";
+      if (/maxBuffer|stdout maxBuffer/i.test(detail)) {
+        throw new WorkspaceRegistryError("workspace_invalid", "Workspace annotations object is too large");
+      }
+      throw this.sanitizeGitError(error);
+    }
+  }
+
   /** Write only a validated API-owned artifact below the checked-out repository. */
   async writeRegistryFile(path: string, source: string): Promise<void> {
     this.assertRegistryArtifactPath(path);

backend/src/workspaces/registry.ts

@@ -3,6 +3,7 @@ import { lstatSync } from "node:fs";
 import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { buildInstallationContract, renderWorkspaceDocs } from "./contracts.js";
+import { parseAnnotationsYaml } from "./annotations.js";
 import { assertCatalogMatchesDescriptor, parseWorkspaceCatalogYaml, type WorkspaceCatalog, type WorkspaceCatalogEntry } from "./catalog.js";
 import {
   GitWorkspaceRepository,
@@ -581,6 +582,10 @@ export class WorkspaceRegistry {
         }
         assertCatalogMatchesDescriptor(entry, workspace);
         await this.assertEvidenceContext(workspace, safeHead);
+        const annotations = await this.repository.annotationsObject(safeHead, id);
+        if (annotations !== undefined) {
+          parseAnnotationsYaml(annotations.contents.toString("utf8"));
+        }
         const collection = workspace.semantic_index.vector_store.collection;
         const owner = collectionOwners.get(collection);
         if (owner !== undefined) {