@malloy-publisher/server 0.0.227 → 0.0.228

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/README.docker.md +8 -8
  2. package/dist/app/assets/{EnvironmentPage-DvOJ7L_b.js → EnvironmentPage-EW2lbGvb.js} +1 -1
  3. package/dist/app/assets/{HomePage-CXguJsXS.js → HomePage-Bkwc9Woc.js} +1 -1
  4. package/dist/app/assets/{LightMode-ZsshUznu.js → LightMode-Bum_KBpN.js} +1 -1
  5. package/dist/app/assets/{MainPage-BIe0VwBa.js → MainPage-oiEy7TNM.js} +1 -1
  6. package/dist/app/assets/{MaterializationsPage-BuZ6UJVx.js → MaterializationsPage-C_VJsTgU.js} +1 -1
  7. package/dist/app/assets/{ModelPage-DsPf-s8B.js → ModelPage-z8REqAmk.js} +1 -1
  8. package/dist/app/assets/{PackagePage-CEVNAKZa.js → PackagePage-C2Vtt1Ln.js} +1 -1
  9. package/dist/app/assets/{RouteError-Chn7lL96.js → RouteError-DmJLpLXm.js} +1 -1
  10. package/dist/app/assets/{ThemeEditorPage-DWC_FdNU.js → ThemeEditorPage-BywFjC7A.js} +1 -1
  11. package/dist/app/assets/{WorkbookPage-CGrsFz8p.js → WorkbookPage-DCMizDMR.js} +1 -1
  12. package/dist/app/assets/{core-vVgoO8IR.es-BD_THWs_.js → core-CEDZMHV1.es-_yGzNgNH.js} +1 -1
  13. package/dist/app/assets/{index-D6YtyiJ0.js → index-CE9xhdra.js} +1 -1
  14. package/dist/app/assets/{index-BioohWQj.js → index-CdmFub34.js} +1 -1
  15. package/dist/app/assets/{index-gEWxu09x.js → index-DDMrjIT3.js} +1 -1
  16. package/dist/app/assets/{index-DNUZpnaa.js → index-EqslXZ44.js} +4 -4
  17. package/dist/app/index.html +1 -1
  18. package/dist/default-publisher.config.json +7 -7
  19. package/dist/runtime/publisher.js +5 -0
  20. package/dist/server.mjs +841 -963
  21. package/package.json +1 -1
  22. package/publisher.config.example.bigquery.json +7 -7
  23. package/publisher.config.example.duckdb.json +7 -7
  24. package/publisher.config.json +7 -11
  25. package/src/config.spec.ts +2 -2
  26. package/src/controller/package.controller.ts +62 -31
  27. package/src/default-publisher.config.json +7 -7
  28. package/src/mcp/handler_utils.spec.ts +108 -0
  29. package/src/mcp/handler_utils.ts +98 -4
  30. package/src/mcp/server.protocol.spec.ts +58 -0
  31. package/src/mcp/server.ts +29 -1
  32. package/src/mcp/skills/skills_bundle.json +1 -1
  33. package/src/mcp/tools/compile_tool.spec.ts +207 -0
  34. package/src/mcp/tools/compile_tool.ts +177 -0
  35. package/src/mcp/tools/execute_query_tool.spec.ts +143 -0
  36. package/src/mcp/tools/execute_query_tool.ts +37 -4
  37. package/src/mcp/tools/get_context_tool.ts +1 -1
  38. package/src/mcp/tools/reload_package_tool.spec.ts +232 -0
  39. package/src/mcp/tools/reload_package_tool.ts +158 -0
  40. package/src/runtime/publisher.js +5 -0
  41. package/src/server.ts +7 -5
  42. package/src/service/environment.ts +70 -6
  43. package/src/service/model.spec.ts +92 -0
  44. package/src/service/model.ts +58 -7
  45. package/src/service/package.ts +31 -13
  46. package/src/service/package_reload_safety.spec.ts +193 -0
  47. package/tests/fixtures/query-givens/data/orders.csv +7 -0
  48. package/tests/fixtures/query-givens/model.malloy +34 -0
  49. package/tests/fixtures/query-givens/publisher.json +5 -0
  50. package/tests/integration/mcp/mcp_execute_query_tool.integration.spec.ts +22 -22
  51. package/tests/integration/query_givens/query_givens.integration.spec.ts +146 -0
  52. package/tests/integration/query_givens/query_givens_authorize.integration.spec.ts +121 -0
  53. package/tests/integration/sdk_givens/sdk_givens.integration.spec.ts +110 -0
@@ -0,0 +1,232 @@
1
+ import { describe, expect, it } from "bun:test";
2
+ import { registerReloadPackageTool } from "./reload_package_tool";
3
+ import type { EnvironmentStore } from "../../service/environment_store";
4
+ import { PackageNotFoundError, ServiceUnavailableError } from "../../errors";
5
+
6
+ // Capture the handler registerReloadPackageTool passes to McpServer.tool, so it
7
+ // can be exercised against a mocked EnvironmentStore. The tool builds a
8
+ // PackageController internally, which calls environment.getPackage(pkg, reload),
9
+ // so the mock only needs getEnvironment -> { getPackage }.
10
+ type Handler = (params: Record<string, unknown>) => Promise<{
11
+ isError?: boolean;
12
+ content: Array<{ resource: { text: string } }>;
13
+ }>;
14
+
15
+ function captureHandler(store: Partial<EnvironmentStore>): Handler {
16
+ let handler: Handler | undefined;
17
+ const fakeServer = {
18
+ tool: (_name: string, _desc: string, _shape: unknown, h: Handler) => {
19
+ handler = h;
20
+ },
21
+ };
22
+ registerReloadPackageTool(fakeServer as never, store as EnvironmentStore);
23
+ if (!handler) throw new Error("handler was not registered");
24
+ return handler;
25
+ }
26
+
27
+ function parse(result: { content: Array<{ resource: { text: string } }> }) {
28
+ return JSON.parse(result.content[0].resource.text);
29
+ }
30
+
31
+ // A store whose package reload returns `metadata`. `location` is left undefined
32
+ // so PackageController takes the in-place-reload branch (no re-download). The
33
+ // optional `calls` array records the `reload` flag of every getPackage call.
34
+ function storeReturning(
35
+ metadata: Record<string, unknown>,
36
+ calls?: boolean[],
37
+ ): Partial<EnvironmentStore> {
38
+ return {
39
+ getEnvironment: async () =>
40
+ ({
41
+ getPackage: async (_pkg: string, reload: boolean) => {
42
+ calls?.push(reload);
43
+ return { getPackageMetadata: () => metadata } as never;
44
+ },
45
+ }) as never,
46
+ };
47
+ }
48
+
49
+ // A store whose cached package metadata carries `location`, so PackageController
50
+ // takes the re-fetch branch: installPackage instead of an in-place recompile.
51
+ // This is the only remaining path that overwrites on-disk edits, so it is worth
52
+ // pinning that the routing and the reported mode both match.
53
+ function storeWithInstallLocation(installed: Record<string, unknown>): {
54
+ store: Partial<EnvironmentStore>;
55
+ installCalls: string[];
56
+ } {
57
+ const installCalls: string[] = [];
58
+ return {
59
+ installCalls,
60
+ store: {
61
+ getEnvironment: async () =>
62
+ ({
63
+ getPackage: async () =>
64
+ ({
65
+ getPackageMetadata: () => ({
66
+ name: "ecommerce",
67
+ location: "https://github.com/example/pkg",
68
+ }),
69
+ }) as never,
70
+ installPackage: async (pkg: string) => {
71
+ installCalls.push(pkg);
72
+ return { getPackageMetadata: () => installed } as never;
73
+ },
74
+ }) as never,
75
+ },
76
+ };
77
+ }
78
+
79
+ const args = { environmentName: "malloy-samples", packageName: "ecommerce" };
80
+
81
+ describe("malloy_reloadPackage tool", () => {
82
+ it("returns status reloaded with the package name", async () => {
83
+ const handler = captureHandler(storeReturning({ name: "ecommerce" }));
84
+ const result = await handler(args);
85
+ expect(result.isError).toBe(false);
86
+ expect(parse(result)).toEqual({
87
+ status: "reloaded",
88
+ mode: "in-place",
89
+ name: "ecommerce",
90
+ });
91
+ });
92
+
93
+ it("includes description and non-empty warnings", async () => {
94
+ const warnings = [
95
+ {
96
+ model: "ecommerce.malloy",
97
+ target: "top_categories",
98
+ severity: "error",
99
+ },
100
+ ];
101
+ const handler = captureHandler(
102
+ storeReturning({ name: "ecommerce", description: "shop", warnings }),
103
+ );
104
+ const parsed = parse(await handler(args));
105
+ expect(parsed).toEqual({
106
+ status: "reloaded",
107
+ mode: "in-place",
108
+ name: "ecommerce",
109
+ description: "shop",
110
+ warnings,
111
+ });
112
+ });
113
+
114
+ it("omits warnings when the reloaded package has none", async () => {
115
+ const handler = captureHandler(
116
+ storeReturning({ name: "ecommerce", warnings: [] }),
117
+ );
118
+ const parsed = parse(await handler(args));
119
+ expect(parsed.warnings).toBeUndefined();
120
+ expect(parsed.status).toBe("reloaded");
121
+ });
122
+
123
+ it("forwards reload=true (recompiles, not just reads)", async () => {
124
+ const calls: boolean[] = [];
125
+ const handler = captureHandler(
126
+ storeReturning({ name: "ecommerce" }, calls),
127
+ );
128
+ await handler(args);
129
+ // The controller probes cached metadata (reload=false) then reloads
130
+ // (reload=true); the tool must trigger the recompile.
131
+ expect(calls).toContain(true);
132
+ });
133
+
134
+ it("surfaces a thrown error as a tool error, not a transport fault", async () => {
135
+ const handler = captureHandler({
136
+ getEnvironment: async () => {
137
+ throw new Error("Environment 'nope' could not be resolved");
138
+ },
139
+ });
140
+ const result = await handler({ ...args, environmentName: "nope" });
141
+ expect(result.isError).toBe(true);
142
+ expect(parse(result).error).toBeDefined();
143
+ });
144
+
145
+ it("reports a missing package as not-found, not as a Malloy syntax problem", async () => {
146
+ // Pin the remediation text, not just that an error came back. Asserting
147
+ // only that `error` is defined is what let every error class funnel
148
+ // through the Malloy helper unnoticed: a typo'd package name told the
149
+ // caller to go check its Malloy syntax.
150
+ const handler = captureHandler({
151
+ getEnvironment: async () => {
152
+ throw new PackageNotFoundError("Package 'nope' not found");
153
+ },
154
+ });
155
+ const parsed = parse(await handler({ ...args, packageName: "nope" }));
156
+ expect(parsed.error).toContain("Resource not found");
157
+ expect(JSON.stringify(parsed.suggestions)).not.toContain("Malloy file");
158
+ });
159
+
160
+ it("reports back-pressure as retryable, not as a Malloy syntax problem", async () => {
161
+ const handler = captureHandler({
162
+ getEnvironment: async () => {
163
+ throw new ServiceUnavailableError("Memory limit reached");
164
+ },
165
+ });
166
+ const parsed = parse(await handler(args));
167
+ expect(parsed.error).toContain("Memory limit reached");
168
+ expect(JSON.stringify(parsed.suggestions)).toContain("Retry");
169
+ expect(JSON.stringify(parsed.suggestions)).not.toContain("Malloy file");
170
+ });
171
+
172
+ it("surfaces a hard compile failure on reload as a tool error", async () => {
173
+ // A Package.create compile failure propagates out of environment.getPackage
174
+ // (the reload site), not out of getEnvironment. The controller swallows the
175
+ // first probe call and re-throws on the reload call.
176
+ const handler = captureHandler({
177
+ getEnvironment: async () =>
178
+ ({
179
+ getPackage: async () => {
180
+ throw new Error("'nonexistent_status_field' is not defined");
181
+ },
182
+ }) as never,
183
+ });
184
+ const result = await handler(args);
185
+ expect(result.isError).toBe(true);
186
+ expect(parse(result).error).toBeDefined();
187
+ });
188
+
189
+ it("reports mode in-place for a package with no install location", async () => {
190
+ const handler = captureHandler(storeReturning({ name: "ecommerce" }));
191
+ expect(parse(await handler(args)).mode).toBe("in-place");
192
+ });
193
+
194
+ it("re-fetches and reports mode reinstalled when the package carries an install location", async () => {
195
+ // The one path that still overwrites on-disk edits. It must route through
196
+ // installPackage, and the payload must say so, since an agent cannot
197
+ // otherwise tell that its saved edit was just re-fetched over.
198
+ const { store, installCalls } = storeWithInstallLocation({
199
+ name: "ecommerce",
200
+ location: "https://github.com/example/pkg",
201
+ });
202
+ const handler = captureHandler(store);
203
+ const result = await handler(args);
204
+ expect(result.isError).toBe(false);
205
+ expect(installCalls).toEqual(["ecommerce"]);
206
+ expect(parse(result).mode).toBe("reinstalled");
207
+ });
208
+
209
+ it("never echoes the package location back to the caller", async () => {
210
+ // The payload hand-picks fields; REST spreads the whole ApiPackage. Pin
211
+ // that the allowlist holds, since location is the one field here that is
212
+ // deployment detail rather than something an agent needs.
213
+ const { store } = storeWithInstallLocation({
214
+ name: "ecommerce",
215
+ location: "https://github.com/example/pkg",
216
+ });
217
+ const parsed = parse(await captureHandler(store)(args));
218
+ expect(parsed.location).toBeUndefined();
219
+ });
220
+
221
+ it("surfaces exploresWarnings (a mistyped explores entry is not swallowed)", async () => {
222
+ const exploresWarnings = [
223
+ "explore 'ordrs' does not resolve to a model in this package",
224
+ ];
225
+ const handler = captureHandler(
226
+ storeReturning({ name: "ecommerce", exploresWarnings }),
227
+ );
228
+ const parsed = parse(await handler(args));
229
+ expect(parsed.status).toBe("reloaded");
230
+ expect(parsed.exploresWarnings).toEqual(exploresWarnings);
231
+ });
232
+ });
@@ -0,0 +1,158 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import { z } from "zod";
3
+ import { logger } from "../../logger";
4
+ import { EnvironmentStore } from "../../service/environment_store";
5
+ import { PackageController } from "../../controller/package.controller";
6
+ import { type ErrorDetails } from "../error_messages";
7
+ import { buildMalloyUri, classifyToolError } from "../handler_utils";
8
+
9
+ // Zod shape for malloy_reloadPackage. environmentName/packageName mirror the
10
+ // other tools and point the agent at malloy_getContext for name discovery.
11
+ const reloadShape = {
12
+ environmentName: z
13
+ .string()
14
+ .describe(
15
+ "Environment name. Call malloy_getContext with no arguments to list the available environments.",
16
+ ),
17
+ packageName: z
18
+ .string()
19
+ .describe(
20
+ "Package to reload. Call malloy_getContext with just environmentName to list its packages.",
21
+ ),
22
+ };
23
+
24
+ /**
25
+ * What a failed reload does, in one sentence, shared with MCP_INSTRUCTIONS
26
+ * rather than restated there. Both surfaces describe the same behavior, so one
27
+ * copy is what stops them drifting.
28
+ *
29
+ * SECURITY: interpolated into MCP_INSTRUCTIONS, which is delivered
30
+ * pre-authorization to any connecting client. Keep this a static string
31
+ * literal; never derive it from config, environment, or request data.
32
+ */
33
+ export const RELOAD_FAILURE_IS_SAFE =
34
+ "A reload that fails to compile leaves your files on disk alone and keeps serving the previously compiled model, returning the compile errors.";
35
+
36
+ const RELOAD_DESCRIPTION = `Reload a package so edits to its model files on disk are picked up, making newly added or changed sources, views, and named queries resolvable by malloy_executeQuery WITHOUT restarting the server. Publisher compiles each configured package at boot and serves that cached model, so a source or view you add afterwards is not queryable by name until the package is reloaded. Use this to close the edit -> run loop after saving a model change.
37
+
38
+ ${RELOAD_FAILURE_IS_SAFE} Running malloy_compile first is still the faster way to see diagnostics, and it keeps a broken model from ever reaching the reload.
39
+
40
+ ## Parameters
41
+ - environmentName, packageName (required): the package to recompile. Use the names malloy_getContext returns.
42
+
43
+ ## Behavior
44
+ Recompiles the package from its current on-disk content under publisher_data/, so your saved edits are picked up. This is the path every package from publisher.config.json takes. A package whose stored metadata carries an install location (only a PATCH that supplies one sets it) is re-fetched from that source instead, which overwrites on-disk edits.
45
+
46
+ ## Response
47
+ A JSON object with status "reloaded", a mode of "in-place" or "reinstalled", the package name, any render-tag warnings, and any exploresWarnings (curated-discovery entries that did not resolve to a model). Check mode if you had unsaved-elsewhere edits on disk: "in-place" recompiled them, "reinstalled" re-fetched over them. A reload that hits a hard compile error returns an error payload instead.`;
48
+
49
+ /**
50
+ * Registers the malloy_reloadPackage MCP tool: recompiles a package from its
51
+ * on-disk content so a saved model edit becomes queryable by name without a
52
+ * server restart. Wraps the same PackageController.getPackage(reload=true) path
53
+ * the REST GET /environments/:env/packages/:pkg?reload=true endpoint uses, so it
54
+ * adds no capability beyond that already-exposed endpoint (SECURITY: parity with
55
+ * REST. The MCP surface is unauthenticated, and so is that endpoint; a reload
56
+ * mutates the shared in-memory package but returns only names and warnings,
57
+ * never row data or the package's location).
58
+ */
59
+ export function registerReloadPackageTool(
60
+ mcpServer: McpServer,
61
+ environmentStore: EnvironmentStore,
62
+ ): void {
63
+ const packageController = new PackageController(environmentStore);
64
+
65
+ mcpServer.tool(
66
+ "malloy_reloadPackage",
67
+ RELOAD_DESCRIPTION,
68
+ reloadShape,
69
+ async (params) => {
70
+ const { environmentName, packageName } = params;
71
+
72
+ logger.info("[MCP Tool reloadPackage] Reloading package", {
73
+ environmentName,
74
+ packageName,
75
+ });
76
+
77
+ const uri = buildMalloyUri(
78
+ { environment: environmentName, package: packageName },
79
+ "reloadPackage",
80
+ );
81
+
82
+ try {
83
+ const { metadata: pkg, mode } =
84
+ await packageController.reloadPackage(
85
+ environmentName,
86
+ packageName,
87
+ );
88
+
89
+ const payload = {
90
+ status: "reloaded" as const,
91
+ // Which path ran. "in-place" recompiled the tree on disk and left
92
+ // it alone; "reinstalled" re-fetched from the package's install
93
+ // location, so any on-disk edits are gone. The caller cannot tell
94
+ // these apart otherwise, and only one of them keeps their work.
95
+ mode,
96
+ name: pkg.name,
97
+ ...(pkg.description !== undefined && {
98
+ description: pkg.description,
99
+ }),
100
+ ...(pkg.warnings !== undefined &&
101
+ pkg.warnings.length > 0 && { warnings: pkg.warnings }),
102
+ // exploresWarnings is a distinct signal from render-tag warnings:
103
+ // it flags a curated-discovery (explores) entry that did not
104
+ // resolve to a model, so a mistyped explores edit is not silently
105
+ // swallowed on reload.
106
+ ...(pkg.exploresWarnings !== undefined &&
107
+ pkg.exploresWarnings.length > 0 && {
108
+ exploresWarnings: pkg.exploresWarnings,
109
+ }),
110
+ };
111
+
112
+ return {
113
+ isError: false,
114
+ content: [
115
+ {
116
+ type: "resource" as const,
117
+ resource: {
118
+ type: "application/json",
119
+ uri,
120
+ text: JSON.stringify(payload),
121
+ },
122
+ },
123
+ ],
124
+ };
125
+ } catch (error) {
126
+ // Unknown environment/package, or a compile error in the reloaded
127
+ // package: surface as a clean isError payload rather than a
128
+ // transport fault.
129
+ logger.warn("[MCP Tool reloadPackage] reload failed", {
130
+ environmentName,
131
+ packageName,
132
+ error: error instanceof Error ? error.message : String(error),
133
+ });
134
+ const errorDetails: ErrorDetails = classifyToolError(
135
+ "reloadPackage",
136
+ `${environmentName}/${packageName}`,
137
+ error,
138
+ );
139
+ return {
140
+ isError: true,
141
+ content: [
142
+ {
143
+ type: "resource" as const,
144
+ resource: {
145
+ type: "application/json",
146
+ uri,
147
+ text: JSON.stringify({
148
+ error: errorDetails.message,
149
+ suggestions: errorDetails.suggestions,
150
+ }),
151
+ },
152
+ },
153
+ ],
154
+ };
155
+ }
156
+ },
157
+ );
158
+ }
@@ -5,6 +5,10 @@
5
5
  // Exposes window.Publisher with:
6
6
  // - Publisher.query(model, malloy, opts?) → Promise<rows[]>
7
7
  // - Publisher.queryFull(model, malloy, opts?) → Promise<MalloyResult> (envelope for <malloy-render>)
8
+ // opts: { environment?, package?, sourceName?, queryName?, filterParams?,
9
+ // bypassFilters?, givens? }. givens is a name→value map bound as
10
+ // Malloy given: runtime parameters for this query (safe parameterization,
11
+ // not string interpolation) — see the malloy-html-data-app-runtime skill.
8
12
  // - Publisher.embed(selector, { src, height?, token? })
9
13
  // - Publisher.context ({ environment, package } inferred from URL)
10
14
  // - Publisher.setToken(token) (override Bearer token; default uses cookies)
@@ -92,6 +96,7 @@
92
96
  if (opts.queryName) body.queryName = opts.queryName;
93
97
  if (opts.filterParams) body.filterParams = opts.filterParams;
94
98
  if (opts.bypassFilters) body.bypassFilters = true;
99
+ if (opts.givens) body.givens = opts.givens;
95
100
 
96
101
  var headers = Object.assign(
97
102
  { "content-type": "application/json" },
package/src/server.ts CHANGED
@@ -102,7 +102,7 @@ function parseArgs() {
102
102
  " --port <number> Port to run the server on (default: 4000)",
103
103
  );
104
104
  console.log(
105
- " --host <string> Host to bind the server to (default: localhost)",
105
+ " --host <string> Host to bind the REST and MCP servers to (default: 0.0.0.0)",
106
106
  );
107
107
  console.log(
108
108
  " --server_root <path> Root directory to serve files from (default: .)",
@@ -120,7 +120,7 @@ function parseArgs() {
120
120
  " --shutdown_graceful_close_timeout_seconds <number> Time in seconds to wait after closing servers before exit (default: 0)",
121
121
  );
122
122
  console.log(
123
- " --init Initialize the storage (default: false)",
123
+ " --init Wipe persisted storage and re-sync it from the config (default: false)",
124
124
  );
125
125
  console.log(
126
126
  " --watch-env <name> Enable dev-mode watch for the named environment.",
@@ -147,7 +147,7 @@ function parseArgs() {
147
147
  // this — the user told us where to look. Skip in NODE_ENV=test as a
148
148
  // belt-and-suspenders so any spec that ends up evaluating this
149
149
  // module doesn't accidentally pin the EnvironmentStore to the
150
- // bundled malloy-samples config.
150
+ // bundled examples config.
151
151
  if (!sawServerRoot && !sawConfig && process.env.NODE_ENV !== "test") {
152
152
  process.env.PUBLISHER_USE_BUNDLED_DEFAULT = "true";
153
153
  }
@@ -1613,13 +1613,15 @@ app.get(
1613
1613
  );
1614
1614
 
1615
1615
  app.post(
1616
- `${API_PREFIX}/environments/:environmentName/packages/:packageName/models/:modelName/compile`,
1616
+ `${API_PREFIX}/environments/:environmentName/packages/:packageName/models/*?/compile`,
1617
1617
  async (req, res) => {
1618
1618
  try {
1619
+ // Express stores wildcard matches in params['0'], so nested model
1620
+ // paths (models in subdirectories) compile just like they query.
1619
1621
  const result = await compileController.compile(
1620
1622
  req.params.environmentName,
1621
1623
  req.params.packageName,
1622
- req.params.modelName,
1624
+ (req.params as Record<string, string>)["0"],
1623
1625
  req.body.source,
1624
1626
  req.body.includeSql === true,
1625
1627
  req.body.givens as Record<string, GivenValue> | undefined,
@@ -471,9 +471,30 @@ export class Environment {
471
471
  if (includeSql && queryMaterializer) {
472
472
  try {
473
473
  sql = await queryMaterializer.getSQL({ givens });
474
- } catch {
475
- // Source may not contain a runnable query (e.g. only source definitions),
476
- // in which case we simply omit the sql field.
474
+ } catch (error) {
475
+ // A bad caller given (unknown name, wrong-typed value, finalized
476
+ // override, ...) surfaces as a Malloy `runtime-given-*` error.
477
+ // Map it to a 400 rather than silently omitting `sql` (which is
478
+ // indistinguishable from "no runnable query"). Duck-type on
479
+ // `.code`; let a MalloyError fall to the outer catch → problems.
480
+ // The `runtime-given-` prefix is pinned to Malloy's error codes
481
+ // (given_binding.ts / runtime.ts, same as model.ts) — if they're
482
+ // renamed upstream a bad given would silently revert to the omit
483
+ // branch below, so keep the two in sync.
484
+ const givenCode = (error as { code?: string })?.code;
485
+ if (
486
+ typeof givenCode === "string" &&
487
+ givenCode.startsWith("runtime-given-")
488
+ ) {
489
+ throw new BadRequestError(
490
+ error instanceof Error ? error.message : String(error),
491
+ );
492
+ }
493
+ if (error instanceof MalloyError) {
494
+ throw error;
495
+ }
496
+ // Otherwise the source may just not contain a runnable query
497
+ // (e.g. only source definitions) — omit the sql field.
477
498
  }
478
499
  }
479
500
 
@@ -860,8 +881,17 @@ export class Environment {
860
881
  return _package;
861
882
  } catch (error) {
862
883
  logger.error(`Failed to load package ${packageName}`, { error });
863
- this.packages.delete(packageName);
864
- this.packageStatuses.delete(packageName);
884
+ if (existingPackage !== undefined && reload) {
885
+ // A failed RELOAD must not take down a package that is already
886
+ // serving. The compiled model in `packages` is still the last good
887
+ // one (it is only replaced on success), so keep serving it and let
888
+ // the caller surface the error instead of evicting the package and
889
+ // leaving the environment with nothing to answer from.
890
+ this.setPackageStatus(packageName, PackageStatus.SERVING);
891
+ } else {
892
+ this.packages.delete(packageName);
893
+ this.packageStatuses.delete(packageName);
894
+ }
865
895
  throw error;
866
896
  }
867
897
  }
@@ -1019,6 +1049,10 @@ export class Environment {
1019
1049
  packageName,
1020
1050
  canonicalPath,
1021
1051
  () => this.malloyConfig.malloyConfig,
1052
+ // This tree was just staged into place by the rename above, so a
1053
+ // failed load leaves a half-built directory that is ours to
1054
+ // remove; the rollback below restores the previous one.
1055
+ true,
1022
1056
  );
1023
1057
  // Strict-reject hook (publish/update only — reload passes no
1024
1058
  // validator and stays fail-safe). Throw INSIDE the try so the
@@ -1064,7 +1098,37 @@ export class Environment {
1064
1098
  await fs.promises
1065
1099
  .rm(stagingPath, { recursive: true, force: true })
1066
1100
  .catch(() => {});
1067
- this.deletePackageStatus(packageName);
1101
+ if (oldPackage && restored) {
1102
+ // The rollback put the old tree back and the previous package is
1103
+ // still in `this.packages` (it is only replaced on success
1104
+ // below), so it is genuinely still serving. Deleting its status
1105
+ // would strand it: listPackages enumerates packageStatuses, so
1106
+ // the package would answer getPackage while being invisible to
1107
+ // listings and discovery until a restart.
1108
+ this.setPackageStatus(packageName, PackageStatus.SERVING);
1109
+ } else {
1110
+ // Either there was nothing to fall back to (a first install), or
1111
+ // the restore did not happen: the rename-back threw, or the old
1112
+ // tree was never on disk to retire. The canonical path is then
1113
+ // missing or still holds the rejected content, so the cached
1114
+ // package no longer matches disk and must not be advertised as
1115
+ // serving. Drop both, and keep the two maps agreeing.
1116
+ this.deletePackageStatus(packageName);
1117
+ if (oldPackage) {
1118
+ // Retire before dropping it, the same way every other eviction
1119
+ // here does: once it leaves this.packages, closeAllConnections
1120
+ // can no longer reach its MalloyConfig, so its native handles
1121
+ // would never be released. Retire rather than shut down
1122
+ // inline, because withPackageLock does not cover queries that
1123
+ // already took this Package from an earlier getPackage; the
1124
+ // drain lets those finish first.
1125
+ this.retireConnectionGeneration(
1126
+ `package ${packageName}`,
1127
+ () => oldPackage.getMalloyConfig().shutdown("close"),
1128
+ );
1129
+ }
1130
+ this.packages.delete(packageName);
1131
+ }
1068
1132
  logger.debug("install.phase2.rollback", {
1069
1133
  environmentName: this.environmentName,
1070
1134
  packageName,
@@ -444,6 +444,55 @@ describe("service/model", () => {
444
444
  sinon.restore();
445
445
  });
446
446
 
447
+ it("maps a finalized-given rejection (code) to BadRequestError, not 500", async () => {
448
+ // Malloy throws this (extends Error, not MalloyError, not root-exported)
449
+ // when a client supplies a given an operator finalized. model.ts
450
+ // duck-types on `.code`; guard against that mapping regressing.
451
+ const finalizedErr = Object.assign(
452
+ new Error(
453
+ "Given 'region' is finalized and cannot be overridden",
454
+ ),
455
+ { code: "runtime-given-finalized" },
456
+ );
457
+ const runnableStub = {
458
+ getPreparedResult: sinon.stub().rejects(finalizedErr),
459
+ run: sinon.stub(),
460
+ };
461
+ const modelMaterializer = {
462
+ loadQuery: sinon.stub().returns(runnableStub),
463
+ loadRestrictedQuery: sinon.stub().returns(runnableStub),
464
+ };
465
+
466
+ const model = new Model(
467
+ packageName,
468
+ mockModelPath,
469
+ {},
470
+ "model",
471
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
472
+ modelMaterializer as any,
473
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
474
+ { contents: {}, exports: [], queryList: [] } as any,
475
+ undefined,
476
+ undefined,
477
+ undefined,
478
+ undefined,
479
+ undefined,
480
+ );
481
+
482
+ await expect(
483
+ model.getQueryResults(
484
+ undefined,
485
+ undefined,
486
+ "run: orders -> summary",
487
+ undefined,
488
+ undefined,
489
+ { region: "EU" },
490
+ ),
491
+ ).rejects.toThrow(BadRequestError);
492
+
493
+ sinon.restore();
494
+ });
495
+
447
496
  /**
448
497
  * The row/byte caps live in `model_limits.ts` (unit-tested in
449
498
  * `model_limits.spec.ts`); these tests just confirm the wiring —
@@ -684,6 +733,49 @@ describe("service/model", () => {
684
733
  sinon.restore();
685
734
  });
686
735
 
736
+ it("maps a finalized-given rejection (code) to BadRequestError, not 500", async () => {
737
+ const finalizedErr = Object.assign(
738
+ new Error(
739
+ "Given 'target_code' is finalized and cannot be overridden",
740
+ ),
741
+ { code: "runtime-given-finalized" },
742
+ );
743
+ const cellRunnable = {
744
+ getPreparedResult: sinon.stub().rejects(finalizedErr),
745
+ run: sinon.stub(),
746
+ };
747
+ const runnableCells = [
748
+ {
749
+ type: "code" as const,
750
+ text: "run: orders -> by_code",
751
+ runnable: cellRunnable,
752
+ },
753
+ ];
754
+
755
+ const model = new Model(
756
+ packageName,
757
+ "test.malloynb",
758
+ {},
759
+ "notebook",
760
+ undefined,
761
+ undefined,
762
+ undefined,
763
+ undefined,
764
+ undefined,
765
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
766
+ runnableCells as any,
767
+ undefined,
768
+ );
769
+
770
+ await expect(
771
+ model.executeNotebookCell(0, undefined, undefined, {
772
+ target_code: "AA",
773
+ }),
774
+ ).rejects.toThrow(BadRequestError);
775
+
776
+ sinon.restore();
777
+ });
778
+
687
779
  it("embeds model-level givens in executed cell newSources", async () => {
688
780
  const sourceInfo = { name: "carriers", schema: { fields: [] } };
689
781
  const givens = [