@malloy-publisher/server 0.0.203 → 0.0.205

package/src/server.ts

@@ -47,6 +47,7 @@ import { ManifestService } from "./service/manifest_service";
 import { MaterializationService } from "./service/materialization_service";
 import { normalizeQueryArray } from "./query_param_utils";
 import { PackageMemoryGovernor } from "./service/package_memory_governor";
+import { assertSafePackageName, safeJoinUnderRoot } from "./path_safety";
 
 export { normalizeQueryArray } from "./query_param_utils";
 
@@ -85,6 +86,14 @@ function parseArgs() {
          i++;
       } else if (arg === "--init") {
          process.env.INITIALIZE_STORAGE = "true";
+      } else if (arg === "--watch-env" && args[i + 1]) {
+         // Append (don't overwrite) so multiple --watch-env flags compose
+         // and so an explicit env var pre-set still wins.
+         const existing = process.env.PUBLISHER_WATCH || "";
+         process.env.PUBLISHER_WATCH = existing
+            ? `${existing},${args[i + 1]}`
+            : args[i + 1];
+         i++;
       } else if (arg === "--help" || arg === "-h") {
          console.log("Malloy Publisher Server");
          console.log("");
@@ -115,6 +124,21 @@ function parseArgs() {
          console.log(
             "  --init                 Initialize the storage (default: false)",
          );
+         console.log(
+            "  --watch-env <name>     Enable dev-mode watch for the named environment.",
+         );
+         console.log(
+            "                         Mounts local-dir packages in-place (symlink, not",
+         );
+         console.log(
+            "                         copy) so source-edit live reload works. A comma-",
+         );
+         console.log(
+            "                         separated PUBLISHER_WATCH mounts all listed envs in",
+         );
+         console.log(
+            "                         place, but only the first one auto-reloads.",
+         );
          console.log("  --help, -h             Show this help message");
          process.exit(0);
       }
@@ -286,6 +310,290 @@ mcpApp.all(MCP_ENDPOINT, async (req, res) => {
    }
 });
 
+// ---------------------------------------------------------------------------
+// In-package HTML data apps
+// ---------------------------------------------------------------------------
+// These routes must come before the SPA catch-all and (in dev) the Vite proxy
+// so that:
+//   - `/sdk/publisher.js`     → Publisher runtime helper
+//   - `/environments/<env>/packages/<pkg>/<file.ext>` → static file from
+//                                                       inside the package dir
+//   - `/api/v0/.../events`    → live-reload SSE (registered in API routes
+//                                below; this comment is the cross-reference)
+
+// Serve the runtime helper that in-package HTML pages load via
+// <script src="/sdk/publisher.js">. Path resolved once at module load.
+const PUBLISHER_RUNTIME_PATH = path.join(
+   path.dirname(__filename_esm),
+   "runtime",
+   "publisher.js",
+);
+app.get("/sdk/publisher.js", (_req, res) => {
+   res.type("application/javascript");
+   // Short cache so live edits during local dev show up quickly. In
+   // production this file is content-stable per release.
+   res.setHeader("cache-control", "public, max-age=60");
+   res.setHeader("X-Content-Type-Options", "nosniff");
+   res.sendFile(PUBLISHER_RUNTIME_PATH, (err) => {
+      if (err) {
+         logger.error("Failed to send publisher.js runtime", { error: err });
+         if (!res.headersSent) res.status(500).end();
+      }
+   });
+});
+
+// Serve files from inside a package directory at
+//   /environments/<env>/packages/<pkg>/<relative-path>
+//
+// This route fully owns its prefix — it does NOT fall through to the SPA on
+// missing files, because doing so would mask 404s (and in dev mode the SPA
+// catch-all errors out before it can reply). Behavior:
+//   - `/environments/<env>/packages/<pkg>`      → 302 to `…/<pkg>/`
+//   - `/environments/<env>/packages/<pkg>/`     → serve `<pkgRoot>/public/index.html`
+//   - `/environments/<env>/packages/<pkg>/foo/` → serve `<pkgRoot>/public/foo/index.html`
+//   - `/environments/<env>/packages/<pkg>/<file>` → serve `<pkgRoot>/public/<file>`, or 404
+// Only the package's `public/` directory is web-served. Models, data files, and
+// the publisher.json manifest live outside it and are never reachable here, so
+// nothing can be downloaded around the per-model #(authorize) and query
+// controls. The data stays reachable through the permission-checked query path.
+
+async function serveFromPackage(
+   req: express.Request,
+   res: express.Response,
+): Promise<void> {
+   const subPathRaw = (req.params as Record<string, string>)["0"] ?? "";
+   try {
+      const environment = await environmentStore.getEnvironment(
+         req.params.environmentName,
+         false,
+      );
+      const pkg = await environment.getPackage(req.params.packageName, false);
+      // Only the package's public/ directory is web-served. Models, data, and
+      // the publisher.json manifest live outside it and are never reachable
+      // through this route. This single directory boundary is the whole
+      // access-control story for static files.
+      const publicRoot = path.join(pkg.getPackagePath(), "public");
+
+      // Directory-style fallback: empty path or trailing slash → look for
+      // index.html within that directory.
+      let subPath = subPathRaw;
+      if (subPath === "" || subPath.endsWith("/")) {
+         subPath = subPath + "index.html";
+      }
+
+      // Resolve the requested file under public/ and reject anything that
+      // escapes it (`..`, encoded traversal) before touching the disk.
+      // safeJoinUnderRoot is the shared lexical-containment primitive (it throws
+      // BadRequestError on escape, surfaced as 400 by the outer catch); the
+      // realpath check below additionally catches symlinks inside public/ that
+      // point outward (403).
+      const fullPath = safeJoinUnderRoot(publicRoot, subPath);
+
+      // Containment check via realpath against the resolved public/ root.
+      // Catches symlinks inside public/ that point out (e.g. a malicious
+      // package shipping `public/leak -> /etc/passwd`), and tolerates the
+      // package root itself being a symlink (how watch-mode in-place mount
+      // works): realpath resolves it transparently and legitimate accesses
+      // inside public/ stay within realPublicRoot. Missing public/ dir or
+      // missing file: realpath throws ENOENT and we 404 cleanly instead of
+      // leaking via Express's default error handler.
+      const fsp = await import("fs/promises");
+      let realPublicRoot: string;
+      let realFullPath: string;
+      try {
+         realPublicRoot = await fsp.realpath(publicRoot);
+         realFullPath = await fsp.realpath(fullPath);
+      } catch {
+         if (!res.headersSent) {
+            // Generic 404 with no reflected request input (avoids reflecting
+            // user-controlled path/package name into the response body).
+            res.status(404).end();
+         }
+         return;
+      }
+      const rel = path.relative(realPublicRoot, realFullPath);
+      if (rel.startsWith("..") || path.isAbsolute(rel)) {
+         res.status(403).end();
+         return;
+      }
+
+      // Framing policy only applies to HTML documents — setting it on CSS/JS/
+      // image assets is meaningless and needlessly strips their default
+      // SAMEORIGIN protection. Embeddability defaults to "*" so same-tenant
+      // embeds work out of the box, and is overridable via PUBLISHER_FRAME_ANCESTORS.
+      const ext = path.extname(realFullPath).toLowerCase();
+      if (ext === ".html" || ext === ".htm") {
+         const frameAncestors = process.env.PUBLISHER_FRAME_ANCESTORS || "*";
+         res.setHeader(
+            "Content-Security-Policy",
+            `frame-ancestors ${frameAncestors}`,
+         );
+         res.removeHeader("X-Frame-Options");
+      }
+      // Never let a served asset be MIME-sniffed into a different content type.
+      res.setHeader("X-Content-Type-Options", "nosniff");
+      res.sendFile(realFullPath, (err) => {
+         if (err) {
+            // Own the 404 instead of letting Express fall through to a
+            // catch-all that may error.
+            if (!res.headersSent) {
+               // Generic 404, no reflected request input (see above).
+               res.status(404).end();
+            }
+         }
+      });
+   } catch (e) {
+      // Map service errors to their real status — a bad package name is a 400,
+      // memory back-pressure is a 503 — rather than flattening everything to
+      // 404. A genuine missing file is already handled by the realpath/sendFile
+      // 404 paths above; this catch only sees service-layer failures.
+      if (!res.headersSent) {
+         const { json, status } = internalErrorToHttpError(e as Error);
+         res.status(status).json(json);
+      }
+   }
+}
+
+// `/environments/<env>/packages/<pkg>` (no trailing slash, no path) redirect so
+// relative URLs in the served HTML resolve as expected. Express's default loose
+// matching also catches the trailing-slash form here, so only redirect URLs that
+// don't already end with `/`.
+//
+// Build the target from the validated route params and the parsed query, not
+// from the raw request URL, so it is always this same canonical, same-origin
+// path with a trailing slash. That removes any open-redirect / header-injection
+// surface from user-controlled input, with the slash placed before any query
+// string (e.g. ?embed_token=...).
+app.get(
+   "/environments/:environmentName/packages/:packageName",
+   (req, res, next) => {
+      if (req.path.endsWith("/")) return next();
+      const canonical =
+         `/environments/${encodeURIComponent(req.params.environmentName)}` +
+         `/packages/${encodeURIComponent(req.params.packageName)}/`;
+      const query = new URLSearchParams();
+      for (const [key, value] of Object.entries(req.query)) {
+         if (Array.isArray(value)) {
+            for (const v of value) query.append(key, String(v));
+         } else if (value !== undefined) {
+            query.append(key, String(value));
+         }
+      }
+      const qs = query.toString();
+      res.redirect(308, qs ? `${canonical}?${qs}` : canonical);
+   },
+);
+
+app.get(
+   "/environments/:environmentName/packages/:packageName/*",
+   serveFromPackage,
+);
+
+// List the static HTML pages bundled inside a package. Used by the SPA's
+// package-detail view to surface a clickable list, and by anyone who wants
+// to discover pages programmatically without scraping the directory.
+//
+// Returns a `Page[]` (see api-doc.yaml) — each item carries the relative
+// `path`, the `packageName`, the page `title` (from its <title> tag), and a
+// `resource` URL. `resource` is the root-relative static-serve URL (NOT under
+// `${API_PREFIX}`) because pages are static assets served off the server root,
+// unlike API resources such as `Package.resource`.
+// Recursive depth is capped to keep this cheap for huge package directories.
+const PAGES_DEPTH_CAP = 3;
+type PageItem = {
+   resource: string;
+   packageName: string;
+   path: string;
+   title: string;
+};
+async function listPackagePages(
+   environmentName: string,
+   packageName: string,
+   publicRoot: string,
+): Promise<PageItem[]> {
+   const fs = await import("fs/promises");
+   const out: PageItem[] = [];
+
+   // Resolve the public/ root once and reject any entry whose realpath escapes
+   // it. Same containment defense as serveFromPackage: catches symlinks inside
+   // public/ pointing outside (e.g. `public/leak -> ../report.malloy`) before we
+   // open and read the target's first 4KB for title extraction. A package with
+   // no public/ dir fails realpath here and yields an empty list.
+   let realPublicRoot: string;
+   try {
+      realPublicRoot = await fs.realpath(publicRoot);
+   } catch {
+      return out;
+   }
+
+   async function walk(dir: string, depth: number) {
+      if (depth > PAGES_DEPTH_CAP) return;
+      let entries: import("fs").Dirent[];
+      try {
+         entries = await fs.readdir(dir, { withFileTypes: true });
+      } catch {
+         return;
+      }
+      for (const entry of entries) {
+         if (entry.name.startsWith(".") || entry.name === "node_modules")
+            continue;
+         const full = path.join(dir, entry.name);
+         let realFull: string;
+         try {
+            realFull = await fs.realpath(full);
+         } catch {
+            continue;
+         }
+         const contained = path.relative(realPublicRoot, realFull);
+         if (contained.startsWith("..") || path.isAbsolute(contained)) continue;
+         if (entry.isDirectory()) {
+            await walk(full, depth + 1);
+         } else if (
+            entry.isFile() &&
+            (entry.name.endsWith(".html") || entry.name.endsWith(".htm"))
+         ) {
+            const rel = path.relative(publicRoot, full).replace(/\\/g, "/");
+            // Cheap title extraction: read first 4KB and grep for <title>.
+            let title = rel;
+            try {
+               const fh = await fs.open(full, "r");
+               try {
+                  const buf = Buffer.alloc(4096);
+                  const { bytesRead } = await fh.read(buf, 0, 4096, 0);
+                  const head = buf.slice(0, bytesRead).toString("utf8");
+                  const m = head.match(/<title[^>]*>([^<]+)<\/title>/i);
+                  if (m) title = m[1].trim();
+               } finally {
+                  await fh.close();
+               }
+            } catch {
+               // ignore; fall back to relative path as title
+            }
+            out.push({
+               resource: `/environments/${environmentName}/packages/${packageName}/${rel}`,
+               packageName,
+               path: rel,
+               title,
+            });
+         }
+      }
+   }
+
+   await walk(publicRoot, 0);
+   out.sort((a, b) => {
+      // Surface index.html first, then alphabetical.
+      if (a.path === "index.html") return -1;
+      if (b.path === "index.html") return 1;
+      return a.path.localeCompare(b.path);
+   });
+   return out;
+}
+
+// NOTE: route registration for /pages moved below the CORS middleware so
+// cross-origin SDK consumers (e.g. a customer's React app pointing at
+// `<ServerProvider baseURL="https://publisher.example.com/api/v0">`) get
+// the proper CORS headers. See the registration after `app.use(cors(...))`.
+
 // Only serve static files in production mode
 // Otherwise we proxy to the React dev server
 if (!isDevelopment) {
@@ -343,6 +651,34 @@ try {
 // Register draining guard middleware - must be after health endpoints but before other routes
 app.use(drainingGuard);
 
+// /pages — registered here (post-CORS, post-body-parser, post-draining) so
+// cross-origin SDK consumers and authenticated requests both work.
+app.get(
+   `${API_PREFIX}/environments/:environmentName/packages/:packageName/pages`,
+   async (req, res) => {
+      try {
+         const environment = await environmentStore.getEnvironment(
+            req.params.environmentName,
+            false,
+         );
+         const pkg = await environment.getPackage(
+            req.params.packageName,
+            false,
+         );
+         const pages = await listPackagePages(
+            req.params.environmentName,
+            req.params.packageName,
+            path.join(pkg.getPackagePath(), "public"),
+         );
+         res.json(pages);
+      } catch (error) {
+         logger.error("Failed to list package pages", { error });
+         const { json, status } = internalErrorToHttpError(error as Error);
+         res.status(status).json(json);
+      }
+   },
+);
+
 app.get(`${API_PREFIX}/status`, async (_req, res) => {
    try {
       const status = await environmentStore.getStatus();
@@ -358,6 +694,86 @@ app.get(`${API_PREFIX}/watch-mode/status`, watchModeController.getWatchStatus);
 app.post(`${API_PREFIX}/watch-mode/start`, watchModeController.startWatching);
 app.post(`${API_PREFIX}/watch-mode/stop`, watchModeController.stopWatchMode);
 
+// Live-reload Server-Sent Events stream for in-package HTML dashboards.
+//
+// This endpoint does NOT start watch mode on its own — that's an explicit
+// opt-in (`--watch-env <name>` CLI flag, or `POST /api/v0/watch-mode/start`).
+// Instead it reports whether watch mode is currently active for the requested
+// env via a `mode` event and, if so, fans out file-change events to the
+// browser. This avoids two earlier bugs:
+//   - Auto-starting from the request handler made arbitrary fetches reach
+//     in to mutate global watch-mode state (`event traversal — see below).
+//   - The runtime previously had no way to know "watch mode isn't running,
+//     don't expect reloads"; with the `mode` event it can choose to surface
+//     a small dev indicator (today: silent).
+//
+// Inputs are validated before any state lookup. Names that don't pass the
+// canonical `assertSafePackageName` allowlist get 400 — preventing requests
+// like `/api/v0/environments/%2e%2e/packages/x/events` from reaching the
+// EnvironmentStore at all. We reuse the shared sanitizer rather than a local
+// regex so the rules stay in one place (see path_safety.ts).
+// Cap concurrent live-reload SSE connections so the endpoint can't be used to
+// exhaust server sockets/memory with unbounded long-lived streams. Generous,
+// since legitimate use is one stream per open dashboard tab.
+const MAX_SSE_CONNECTIONS = 1000;
+let sseConnectionCount = 0;
+app.get(
+   `${API_PREFIX}/environments/:environmentName/packages/:packageName/events`,
+   async (req, res) => {
+      const env = req.params.environmentName;
+      const pkg = req.params.packageName;
+      try {
+         assertSafePackageName(env);
+         assertSafePackageName(pkg);
+         const environment = await environmentStore.getEnvironment(env, false);
+         await environment.getPackage(pkg, false); // 404 if missing
+      } catch (error) {
+         const { json, status } = internalErrorToHttpError(error as Error);
+         res.status(status).json(json);
+         return;
+      }
+
+      if (sseConnectionCount >= MAX_SSE_CONNECTIONS) {
+         res.status(503).json({
+            code: 503,
+            message: "Too many live-reload connections; try again shortly.",
+         });
+         return;
+      }
+      sseConnectionCount++;
+
+      res.set({
+         "content-type": "text/event-stream",
+         "cache-control": "no-cache",
+         connection: "keep-alive",
+         // Disable proxy/CDN buffering so events flush immediately.
+         "x-accel-buffering": "no",
+      });
+      res.flushHeaders();
+
+      const watching = watchModeController.isWatching(env);
+      res.write("event: hello\ndata: connected\n\n");
+      res.write(`event: mode\ndata: ${watching ? "enabled" : "disabled"}\n\n`);
+
+      const key = `${env}/${pkg}`;
+      const send = () => {
+         res.write("event: changed\ndata: changed\n\n");
+      };
+      watchModeController.events.on(key, send);
+      // Keep the connection alive through idle proxies (heartbeat every 25s).
+      const heartbeat = setInterval(() => {
+         res.write(": heartbeat\n\n");
+      }, 25000);
+      const cleanup = () => {
+         clearInterval(heartbeat);
+         watchModeController.events.off(key, send);
+         sseConnectionCount--;
+      };
+      // "close" covers both clean and abrupt disconnects on Node >= 20.
+      req.on("close", cleanup);
+   },
+);
+
 app.get(`${API_PREFIX}/environments`, async (_req, res) => {
    try {
       res.status(200).json(await environmentStore.listEnvironments());
@@ -1414,7 +1830,30 @@ registerLegacyRoutes(app, {
 
 // Modify the catch-all route to only serve index.html in production
 if (!isDevelopment) {
-   app.get("*", (_req, res) => res.sendFile(path.resolve(ROOT, "index.html")));
+   const SPA_INDEX = path.resolve(ROOT, "index.html");
+   app.get("*", (req, res) => {
+      res.sendFile(SPA_INDEX, (err) => {
+         if (!err) return;
+         // The SPA bundle isn't built. This happens when running directly
+         // from source (`bun run src/server.ts`) without first running
+         // `bun run build:app`. Return a friendly placeholder rather than
+         // a 500, and surface package URLs the user might be looking for.
+         if (res.headersSent) return;
+         res.status(404)
+            .type("text/html")
+            .send(
+               `<!doctype html><meta charset="utf-8">
+<title>Publisher</title>
+<style>body{font:14px/1.4 -apple-system,system-ui,sans-serif;margin:40px;max-width:720px;color:#222}</style>
+<h1>Publisher is running, but the SPA bundle isn't built.</h1>
+<p>You requested <code>${req.path.replace(/[<>&]/g, (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;" })[c] ?? c)}</code>.
+The Publisher API is available at <a href="/api/v0/environments">/api/v0/environments</a>.</p>
+<p>To get the Publisher web UI, run <code>cd packages/app &amp;&amp; bunx vite build</code>
+or start the server with <code>NODE_ENV=development</code> after launching Vite on <code>:5173</code>.</p>
+<p>For in-package HTML data apps, browse to <code>/environments/&lt;env&gt;/packages/&lt;pkg&gt;/&lt;file&gt;</code> directly.</p>`,
+            );
+      });
+   });
 }
 
 app.use(
@@ -1448,7 +1887,7 @@ mainServer.timeout = 600000;
 mainServer.keepAliveTimeout = 600000;
 mainServer.headersTimeout = 600000;
 
-mainServer.listen(PUBLISHER_PORT, PUBLISHER_HOST, () => {
+mainServer.listen(PUBLISHER_PORT, PUBLISHER_HOST, async () => {
    const address = mainServer.address() as AddressInfo;
    logger.info(
       `Publisher server listening at http://${address.address}:${address.port}`,
@@ -1458,6 +1897,44 @@ mainServer.listen(PUBLISHER_PORT, PUBLISHER_HOST, () => {
          "Running in development mode - proxying to React dev server at http://localhost:5173",
       );
    }
+   // If `--watch-env <name>` (or PUBLISHER_WATCH=name1,name2) was passed,
+   // wait for env initialization to settle, then start watch mode for each
+   // named env. Packages in those envs are already mounted in-place via the
+   // EnvironmentStore in-place path (see `loadEnvironmentIntoDisk`), so the
+   // chokidar watcher will see edits to your source repo and fan them out
+   // to any connected SSE clients.
+   const watchEnvList = (process.env.PUBLISHER_WATCH || "")
+      .split(",")
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+   if (watchEnvList.length > 0) {
+      // The watcher tracks exactly one env at a time (`WatchModeController`
+      // holds a single chokidar instance). Every env in PUBLISHER_WATCH is
+      // still mounted in place (live source) by the EnvironmentStore, but only
+      // the first is watched, so the others do not auto-reload.
+      if (watchEnvList.length > 1) {
+         logger.warn(
+            `Multiple watch environments requested (${watchEnvList.join(
+               ", ",
+            )}); watch mode auto-reloads one at a time. Watching "${
+               watchEnvList[0]
+            }". The others are mounted in place (their source is live) but will not auto-reload. Pass a single --watch-env (or one PUBLISHER_WATCH value) to silence this.`,
+         );
+      }
+      const envName = watchEnvList[0];
+      try {
+         await environmentStore.finishedInitialization;
+         await watchModeController.ensureWatching(envName);
+         logger.info(
+            `Watch mode active for environment "${envName}" (in-place mount, source-edit live reload).`,
+         );
+      } catch (error) {
+         logger.error(
+            `Failed to start watch mode for environment "${envName}"`,
+            { error },
+         );
+      }
+   }
 });
 const mcpServer = mcpApp.listen(MCP_PORT, PUBLISHER_HOST, () => {
    logger.info(`MCP server listening at http://${PUBLISHER_HOST}:${MCP_PORT}`);

package/src/service/annotations.spec.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "bun:test";
+import type { ModelDef } from "@malloydata/malloy";
+import {
+   annotationTexts,
+   isReservedRoute,
+   modelAnnotations,
+} from "./annotations";
+
+// Minimal `ModelDef` carrying only what `modelAnnotations` reads: `modelID`
+// and the `modelAnnotations` registry (modelID → { ownNotes, inheritsFrom }).
+const makeModelDef = (
+   modelID: string,
+   registry: Record<
+      string,
+      {
+         ownNotes: { notes?: string[]; blockNotes?: string[] };
+         inheritsFrom: string[];
+      }
+   >,
+): ModelDef =>
+   ({
+      modelID,
+      modelAnnotations: Object.fromEntries(
+         Object.entries(registry).map(([id, { ownNotes, inheritsFrom }]) => [
+            id,
+            {
+               ownNotes: {
+                  notes: ownNotes.notes?.map((text) => ({ text, at: {} })),
+                  blockNotes: ownNotes.blockNotes?.map((text) => ({
+                     text,
+                     at: {},
+                  })),
+               },
+               inheritsFrom,
+            },
+         ]),
+      ),
+   }) as unknown as ModelDef;
+
+const noteTexts = (def: ModelDef): string[] =>
+   (modelAnnotations(def).notes ?? []).map((note) => note.text);
+
+describe("isReservedRoute", () => {
+   it("treats the empty route (MOTLY / render config) as reserved", () => {
+      expect(isReservedRoute("")).toBe(true);
+   });
+
+   it("treats Malloy's punctuation sigils as reserved", () => {
+      // Form 2 reserves the entire punct-only namespace, not just the
+      // currently-claimed sigils (`!` `@` `"` `:`).
+      for (const route of ["!", "@", '"', ":", "%", "-", "::"]) {
+         expect(isReservedRoute(route)).toBe(true);
+      }
+   });
+
+   it("treats bracketed app routes as not reserved", () => {
+      for (const route of [
+         "doc",
+         "label",
+         "filter",
+         "bar-chart",
+         "https://example.com/ns",
+         "123",
+         "══SECURITY══",
+      ]) {
+         expect(isReservedRoute(route)).toBe(false);
+      }
+   });
+});
+
+describe("modelAnnotations", () => {
+   it("returns the local model's own `##` notes", () => {
+      const def = makeModelDef("local", {
+         local: { ownNotes: { notes: ["## local"] }, inheritsFrom: [] },
+      });
+      expect(noteTexts(def)).toEqual(["## local"]);
+   });
+
+   it("falls back to an imported model's notes when the local model has no own `##` (authorize must not fail open)", () => {
+      // Regression: a `##(authorize)` declared in an imported file must still
+      // flow into the importing file's file-level gate even when the importing
+      // file declares no `##` of its own. An earlier fold kept an empty local
+      // link at the top, so `.notes` returned [] and the gate failed open.
+      const def = makeModelDef("local", {
+         local: { ownNotes: {}, inheritsFrom: ["base"] },
+         base: {
+            ownNotes: { notes: ['## (authorize) request.user == "admin"'] },
+            inheritsFrom: [],
+         },
+      });
+      expect(noteTexts(def)).toEqual([
+         '## (authorize) request.user == "admin"',
+      ]);
+   });
+
+   it("surfaces the local model's notes at the top when both local and import have `##`", () => {
+      const def = makeModelDef("local", {
+         local: { ownNotes: { notes: ["## local"] }, inheritsFrom: ["base"] },
+         base: { ownNotes: { notes: ["## base"] }, inheritsFrom: [] },
+      });
+      // `.notes` is the top (local); `.texts()` flattens the whole lineage
+      // ancestral-first.
+      expect(noteTexts(def)).toEqual(["## local"]);
+      expect(annotationTexts(modelAnnotations(def))).toEqual([
+         "## base",
+         "## local",
+      ]);
+   });
+
+   it("is cycle-safe and returns an empty bundle for a model with no annotations", () => {
+      const def = makeModelDef("local", {
+         local: { ownNotes: {}, inheritsFrom: ["base"] },
+         base: { ownNotes: {}, inheritsFrom: ["local"] }, // back-edge cycle
+      });
+      expect(modelAnnotations(def)).toEqual({});
+      expect(noteTexts(def)).toEqual([]);
+   });
+});