@malloydata/cli 0.0.54 → 0.0.55

package/dist/index.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-process.MALLOY_CLI_VERSION="0.0.54";
+process.MALLOY_CLI_VERSION="0.0.55";
 require('./cli.js')

package/dist/skills/malloy-language-reference.md

@@ -11,12 +11,13 @@ A core design principle is that **most queries are themselves designing a new se
 
 ## Documents and Statements
 
-A Malloy file (`.malloy`) is a sequence of statements, optionally separated by semicolons. There are four statement types:
+A Malloy file (`.malloy`) is a sequence of statements, optionally separated by semicolons. There are five statement types:
 
 - **`import`** — import sources and queries from another `.malloy` file
 - **`source:`** — define a named, reusable data source with its schema and extensions
 - **`query:`** — define a named query (source + view) for reuse
 - **`run:`** — execute a query (the "do it now" statement)
+- **`given:`** — declare model-level parameters supplied at run time (experimental, see Givens)
 
 ```malloy
 import "shared_model.malloy"
@@ -96,6 +97,8 @@ join_cross: other_table on other_table.key = key         -- cross join
 
 The `with` shorthand requires the joined source to have a declared `primary_key`. All joins are left outer by default. There is no right join — Malloy's graph model doesn't need one.
 
+**Choosing `join_one` vs `join_many`:** Ask "for a single row in the base source, can the joined source match more than one row?" If yes → `join_many`. If no (or at most one) → `join_one`. The common mistake is reaching for `join_many` when joining a *lookup or summary table* (e.g., joining an inventory snapshot to a purchase history on a wine key). Even though the joined table may have many rows overall, if each base row resolves to *at most one* joined row, use `join_one`. Use `join_many` only when the join genuinely fans out the base rows — e.g., joining line items to orders, or notes to a wine catalog.
+
 When you reference a joined source's fields, you use dot notation: `carriers.nickname`, `origin_airport.state`. This is one of Malloy's most important abstractions: **the access path to nested data is identical regardless of how the nesting is physically stored.** An array of records embedded in a column, a `join_many` to a separate table, a record-typed column — all are navigated with the same dot notation. The SQL required to traverse these different physical arrangements varies wildly (unnesting arrays, LEFT JOINs, correlated subqueries, ARRAY_AGG), but Malloy hides all of that. You think about the logical shape of your data — "flights have carriers, carriers have a nickname" — and write `carriers.nickname`. The compiler figures out what SQL is needed to get there. This means you can restructure your physical schema (normalize a nested array into a separate table, or denormalize a joined table into a record column) without changing any of the Malloy that references that data.
 
 ## Fields
@@ -417,7 +420,7 @@ Not all annotations are tags. An annotation is just text. Tags are annotations t
 The character(s) immediately after `#` route the annotation to different consumers:
 
 - `# ` (hash-space) — renderer tags, parsed by the Malloy VS Code extension for visualization
-- `##!` — compiler directives (e.g., `##! experimental.parameters`)
+- `##!` — compiler directives (e.g., `##! experimental.parameters`, `##! experimental.givens`)
 - `#"` — reserved for documentation strings
 - `#(appName)` — application-specific tags (e.g., `#(docs) hidden`)
 
@@ -441,6 +444,192 @@ tName.sub.path=value          -- deep path assignment
 
 Values can be unquoted identifiers, quoted strings, numbers, or typed values prefixed with `@` (`@true`, `@false`, `@2024-01-15`).
 
+## Givens (Model-Level Parameters)
+
+**Status: experimental, gated by `##! experimental.givens`.** Naming is provisional.
+
+Givens are values supplied at run time that the model can reference in any expression. The motivating use case is row-level access control — a model written once with `where: x.tenant_id = $TENANT` and the tenant supplied per API call — but they also fit configuration values, session context, and any "one compiled model, many invocations with varying context" pattern.
+
+Givens are model-wide: a single namespace, one value per name per compilation. They are *complementary to* source/query parameters (`source: foo(x :: string) is ...`), not a replacement. Use a parameter when you want two differently-bound copies of the same source side-by-side in one model; use a given when you want one value visible everywhere in the compilation.
+
+### Declaration
+
+The `given:` top-level statement introduces givens, with a name, a type, and an optional default:
+
+```malloy
+given:
+  TENANT :: string
+  MAX_ROWS :: number is 1000
+  CUTOFF_DATE :: date is @2024-01-01
+```
+
+Type can be any Malloy atomic type or compound type, including `filter<T>`:
+
+```malloy
+given:
+  ROLE :: string
+  ALLOWED_ROLES :: string[]
+  SESSION :: { user_id :: string, tenant :: string }
+  TENANT_FILTER :: filter<string>
+```
+
+Defaults are expressions over constants and other givens. Annotations attach to given declarations the same way they attach to sources or measures.
+
+### Reference: the `$` sigil
+
+Inside any expression, a given is referenced with a leading `$`:
+
+```malloy
+source: orders_for_user is orders extend {
+  where: orders.tenant_id = $TENANT
+}
+
+query: recent_orders is orders_for_user -> {
+  where: order_date >= $CUTOFF_DATE
+  limit: $MAX_ROWS
+}
+```
+
+`$` appears *only* at expression references. The other three sites where a given's name appears — declaration, import, and supply (caller side) — use the bare name, because syntactic position already disambiguates. Givens share the top-level declaration namespace with sources/queries/views, so `source: x is ...` plus `given: x :: string` is a name-conflict error.
+
+### Set membership: `expr in $arrayGiven`
+
+The RHS of `in` is either a parenthesized list of expressions (`in (1, 2, x, y * 7)`, same as SQL) or a given with an array value (`in $ARR`). A bare array-typed expression — a dimension, a joined array field, an inline `[a, b, c]` literal — is *not* legal on the RHS; arrays only reach the RHS via the given form.
+
+When a given has array type, `expr in $ARR` tests `expr` against the runtime-bound array; `not in $ARR` is the negation. The left-hand side must match the array's element type (`string in $string[]`, `number in $number[]`, etc.); mismatches are translate-time errors. Records and nested arrays are out of scope.
+
+```malloy
+given:
+  ALLOWED_STATES :: string[]
+  URGENT_STATUSES :: string[]
+
+source: orders extend {
+  where: state in $ALLOWED_STATES
+  dimension: is_urgent is order_status in $URGENT_STATUSES
+}
+```
+
+At SQL emit, the array's contents land in a generated `IN (...)` clause. Empty or `null` arrays collapse to the obvious result (`IN` → `FALSE`, `NOT IN` → `TRUE`). NULL elements inside a non-empty array follow standard SQL `IN` semantics.
+
+To derive a value from an array — typically a boolean gate — *without* the array itself reaching row-position SQL, use an inline given (below).
+
+### Inline givens
+
+An `inline` given is evaluated at **bind time**, before SQL is emitted: its default expression runs against the resolved given values and reduces to a literal, and that literal is what reaches SQL.
+
+```malloy
+given:
+  CAPABILITIES :: string[]
+  inline CAN_READ_ORDERS :: boolean is 'read_orders' in $CAPABILITIES
+  inline CAN_MUTATE :: boolean
+    is 'write_orders' in $CAPABILITIES or 'admin' in $CAPABILITIES
+
+source: orders extend {
+  where: $CAN_READ_ORDERS   -- SQL sees: WHERE ... AND TRUE  (or FALSE)
+}
+```
+
+This is the **row-level access-control gate** pattern: the host supplies a capability list as a regular given, an inline given derives a boolean from it, and only the boolean — not the list — crosses into row-position SQL. The query planner sees a constant predicate.
+
+Rules:
+
+- An inline given **must** have a default. `inline FOO :: number` with no `is` clause is a translate-time error.
+- The default may use:
+  - Boolean and comparison operators: `and`, `or`, `not`, `=`, `!=`, `<`, `<=`, `>`, `>=`
+  - The `in $array` test against another given
+  - Literals (string, number, boolean, null, array) and references to other givens
+- The default cannot call SQL functions, reference fields, or use any operator outside that list. Disallowed operators are reported at translate time with the offending operator names.
+- Inline givens are filtered out of `Model.givens` and `PreparedQuery.givens` — they're computed, not supplied — so introspection-driven UIs don't render editors for them. A caller can still shadow one by binding it explicitly (useful in tests).
+- `inline` is a context-sensitive modifier, not a reserved keyword: fields, sources, views, dimensions, and joins can still be named `inline`.
+
+### Imports
+
+Givens behave like every other top-level named thing under import:
+
+- **Bare import** (`import "b.malloy"`) brings B's full export surface in, including all of B's givens, under their original names.
+- **Selective import** (`import { source1 } from "b.malloy"`) brings in only what's listed. To surface a given to your callers, list it: `import { source1, MAX_ROWS } from "b.malloy"`.
+- **Rename** uses the existing `LOCAL is REMOTE` form: `import { CAP is MAX_ROWS } from "b.malloy"`.
+
+Surfacing controls *who can supply a value*, not whether internal references work. An imported source can reference a given the importer didn't surface; the reference still resolves internally, and at run time the unsurfaced given relies on its declaration-site default.
+
+A common project convention is a shared `tenant_givens.malloy` (declaring `$TENANT`, `$USER_ROLE`, etc.) that every root file bare-imports on line 1, so the project's given contract is visible at the top of any model.
+
+### Satisfiability
+
+A query referencing `$X` is satisfiable if either `$X` is in the model's namespace (so a caller can supply a value) or `$X` has a default at its declaration site. Otherwise the query is unsatisfiable and errors. Latent definitions (views, dimensions, measures) that reference `$X` are fine if no query actually invokes them — satisfiability is a property of running queries.
+
+### Supplying values
+
+Values can be supplied at two layers, which compose (per-query overrides per-runtime):
+
+**Per-runtime** — bound to a `Runtime`, applied as defaults to every query through it. Two paths:
+
+1. **`givensPath` in `malloy-config.json`** points at a JSON file of `name → value`:
+   ```jsonc
+   { "givensPath": "./local-givens.json" }
+   // or env-var indirection (resolved at config load):
+   { "givensPath": { "env": "GAME_STORE_GIVENS" } }
+   ```
+   The values file is a flat JSON map, keys are caller-facing surface names:
+   ```jsonc
+   { "TENANT": "acme", "USER_ROLE": "admin", "CUTOFF_DATE": "2024-01-01" }
+   ```
+
+2. **Direct on the Runtime constructor** (for per-request multi-tenant servers, tests, scripts):
+   ```typescript
+   const runtime = new Runtime({
+     config,
+     givens: { TENANT: claims.tenant_id, USER_ROLE: claims.role },
+     urlReader,
+   });
+   ```
+   Constructor values *merge over* the file at `givensPath` per-key.
+
+**Per-query** — supplied on a single `.run({ givens: ... })` call:
+```typescript
+await query.run({ givens: { STATE_FILTER: "CA", LIMIT_OVERRIDE: 50 } })
+```
+Available on every compile-or-run entry point (`runtime.loadQuery(...).run(options)`, `preparedQuery.getPreparedResult(options)`, `preparedQuery.getSQL(options)`).
+
+The resolved per-runtime values are exposed on `runtime.givens` (read-only) for diagnostics.
+
+### Finalized givens (security primitive)
+
+A multi-tenant deployment usually wants `TENANT`/`USER_ROLE`/`REGION` to be runtime-bound and **un-overridable per-query** — otherwise a downstream endpoint that accidentally accepts user-controlled query params and plumbs them into `.run({ givens: ... })` becomes a tenant-leak vulnerability.
+
+`finalizeGivens` in the config locks names at the API surface:
+
+```jsonc
+{
+  "givensPath": { "env": "GAME_STORE_GIVENS" },
+  "finalizeGivens": ["TENANT", "USER_ROLE", "REGION"]
+}
+```
+
+Finalize doesn't change *what* a given resolves to — only *who* can supply it. A `.run({ givens: { TENANT: ... } })` for a finalized name throws at API entry (named, not silently dropped). Finalized givens are filtered out of `Model.givens` and `PreparedQuery.givens` so introspection-driven UIs don't render editors for locked names.
+
+### JS shapes for supplied values
+
+Both the JSON values file and per-query `givens` maps accept the same per-type shapes:
+
+| Malloy type | JS |
+|---|---|
+| `string` | string |
+| `number` | `number`, `bigint`, or string (precision escape hatch) |
+| `boolean` | boolean |
+| `date` | ISO date string `"2024-01-15"` |
+| `timestamp` (naive) | ISO string without offset — *not* a JS `Date` |
+| `timestamptz` | JS `Date` or ISO string with offset (string preferred — makes TZ choice visible) |
+| `T[]` | JS array |
+| `{ name :: T, ... }` | JS object |
+| `filter<T>` | JS string (Malloy filter expression source) |
+
+Naive timestamp givens reject `Date` because `Date` represents a UTC instant, not a wall-clock value, and `new Date("2001-01-01T00:00:00")` silently picks up the system's local TZ. Type mismatches throw at the boundary with a path that points at the offending location (e.g., `givens.SESSION.user_id: expected string, got number`). `null` is legal for any given type.
+
+### Introspection
+
+`Model.givens` and `PreparedQuery.givens` expose, to the host, the supplyable givens — for whole-model parameter editors and per-query "run this" forms respectively. Each entry carries name, type, default expression (or undefined if the caller must supply), location, and access to declaration-site annotations via `tagParse`/`getTaglines`.
+
 ## How a Malloy Query Becomes SQL
 
 The compilation pipeline has two phases:

package/dist/skills/writing-malloy-with-mcp.md

@@ -11,8 +11,8 @@ This CLI exposes five tools. "Compile" means parse + typecheck + build the model
 |-----------------|----------------------------------------|--------------------------------------------------------------------------------|
 | `compile_file`  | `{ uri, expand? }`                     | Fetch+compile a .malloy file; returns structured model with problems[].        |
 | `compile`       | `{ source, base_uri?, expand? }`       | Same, on an inline source string.                                              |
-| `run_file`      | `{ uri, name?, index? }`               | Execute one run: from a file. `name` wins over `index`; else last run:.        |
-| `run`           | `{ source, base_uri? }`                | Execute the final run: from an inline source.                                  |
+| `run_file`      | `{ uri, name?, index?, givens? }`      | Execute one run: from a file. `name` wins over `index`; else last run:.        |
+| `run`           | `{ source, base_uri?, givens? }`       | Execute the final run: from an inline source.                                  |
 | `list_runs`     | `{ uri }`                              | Cheap discovery: runnable run: + named queries, no model serialization.        |
 
 Every tool returns a uniform `problems[]` with `{ severity, message, code, uri?, line, column, endLine?, endColumn? }`. Compile errors, import-resolution errors, and runtime SQL errors all use this shape.
@@ -79,6 +79,25 @@ Feed that whole thing to `compile`. Imports resolve against `base_uri` if suppli
 - **Mixed reduction/projection** — a single stage uses either `group_by:`/`aggregate:` OR `select:`, not both.
 - **Calculation in source** — `calculate:` (window functions) only lives in queries, never in source definitions.
 
+## Running a query that declares givens
+
+Givens are model-level parameters (`given: TENANT :: string`, referenced as `$TENANT`). When a model declares them:
+
+1. `compile_file` (or `list_runs`) reports `model.givens[]` (full list with type/default) and per-run/per-query `givens: ["NAME", ...]` arrays — the names that run needs supplied.
+2. Pass values to `run`/`run_file` via the `givens` map, keyed by surface name (no `$`):
+
+```jsonc
+{ "uri": "file:///.../model.malloy", "givens": { "TENANT": "acme", "MAX_ROWS": 100 } }
+```
+
+3. **For per-type JS shapes** (date as ISO string, naive timestamp as ISO without offset, record as JS object, `filter<T>` as a Malloy filter source string, etc.) call `language_help("givens")` — the "JS shapes for supplied values" subsection is the canonical reference. Don't guess; the compiler validates and rejects bad shapes with a path to the offending field.
+
+A given with a default is optional in the `givens` map. A given without a default must be supplied or the run fails with a missing-given error.
+
+**Inline givens** (declared `inline NAME :: T is …`) are evaluated at bind time and don't take supplied values, so they are filtered out of `model.givens[]` and the per-run `givens[]` lists. If you see `$X` referenced in source but missing from introspection, it's an inline.
+
+**Array givens with `in`.** The RHS of `in` is either a parenthesized list of expressions (`in (1, 2, x, y * 7)`, as in SQL) or a given with an array value (`in $ARR`). Use the given form (`where: state in $ALLOWED_STATES`) when the values come from outside the model — bare array expressions (a dimension, joined field, `[a, b, c]` literal) are not legal on the RHS.
+
 ## Before writing non-trivial Malloy
 
 Pull the `malloy-language-reference` prompt first. The language has real scoping and typing rules that the compiler will enforce; don't guess.

package/dist/third_party_notices.txt

@@ -34346,7 +34346,7 @@ SOFTWARE.
   -------
   Package: @databricks/sql
   Url: https://github.com/databricks/databricks-sql-nodejs#readme
-  License(s): Apache 2.0
+  License(s): Apache-2.0
   License Text:
                                  Apache License
                            Version 2.0, January 2004

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@malloydata/cli",
-  "version": "0.0.54",
+  "version": "0.0.55",
   "description": "Malloy CLI",
   "bin": {
     "malloy-cli": "dist/index.js",
@@ -72,14 +72,14 @@
     "@commander-js/extra-typings": "^12.1.0",
     "@duckdb/node-api": "1.4.4-r.1",
     "@duckdb/node-bindings": "1.4.4-r.1",
-    "@malloydata/db-bigquery": "0.0.387",
-    "@malloydata/db-duckdb": "0.0.387",
-    "@malloydata/db-postgres": "0.0.387",
-    "@malloydata/db-snowflake": "0.0.387",
-    "@malloydata/db-trino": "0.0.387",
-    "@malloydata/malloy": "0.0.387",
-    "@malloydata/malloy-connections": "0.0.387",
-    "@malloydata/malloy-sql": "0.0.387",
+    "@malloydata/db-bigquery": "0.0.402",
+    "@malloydata/db-duckdb": "0.0.402",
+    "@malloydata/db-postgres": "0.0.402",
+    "@malloydata/db-snowflake": "0.0.402",
+    "@malloydata/db-trino": "0.0.402",
+    "@malloydata/malloy": "0.0.402",
+    "@malloydata/malloy-connections": "0.0.402",
+    "@malloydata/malloy-sql": "0.0.402",
     "@types/jest": "^29.2.5",
     "@types/node": "^14.11.2",
     "@typescript-eslint/eslint-plugin": "^5.48.2",