@malloydata/malloy 0.0.398 → 0.0.400

package/dist/api/annotation-utils.d.ts

@@ -0,0 +1,36 @@
+import type * as Malloy from '@malloydata/malloy-interfaces';
+import type { Tag } from '@malloydata/malloy-tag';
+/**
+ * The route a stable {@link Malloy.Annotation} belongs to (`''` for MOTLY
+ * tags, `!` for compiler flags, `myApp` for an app's claimed route, etc.).
+ * Returns `undefined` if the annotation's prefix is malformed.
+ */
+export declare function routeOf(a: Malloy.Annotation): string | undefined;
+/**
+ * The payload of a stable {@link Malloy.Annotation} — the substring after
+ * the prefix and separator (`'name=foo'` for `'#(filter) name=foo'`,
+ * `'tag\n'` for `'# tag\n'` — the lexer keeps the trailing newline).
+ * Returns the empty string for an annotation that has no content.
+ */
+export declare function payloadOf(a: Malloy.Annotation): string;
+/**
+ * Filter `annotations` to just those on `route`, in input order.
+ *
+ * Annotations with `malformed-route` prefixes are excluded (no clean route
+ * to resolve to). `reserved-route` annotations *are* included — their
+ * prefix parses to a real route and the user got a compile-time warning,
+ * but the data is what it is.
+ *
+ * Route filtering is level-blind: `# tag` and `## tag` both resolve to
+ * route `''`. Producers separate object-level from model-level annotations
+ * into different arrays; consumers pass the array carrying the right level.
+ */
+export declare function annotationsForRoute(annotations: Malloy.Annotation[] | undefined, route: string): Malloy.Annotation[];
+/**
+ * Parse a stable `Malloy.Annotation[]`'s `route` annotations as MOTLY into
+ * one Tag. The stable counterpart to `Annotations.parseAsTag` — consumes
+ * the flat wire shape, no source offsets. Selection follows
+ * {@link annotationsForRoute} semantics (level-blind, malformed-route
+ * excluded, reserved-route included).
+ */
+export declare function tagFromAnnotations(annotations: Malloy.Annotation[] | undefined, route: string): Tag;

package/dist/api/annotation-utils.js

@@ -0,0 +1,76 @@
+"use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routeOf = routeOf;
+exports.payloadOf = payloadOf;
+exports.annotationsForRoute = annotationsForRoute;
+exports.tagFromAnnotations = tagFromAnnotations;
+const malloy_tag_1 = require("@malloydata/malloy-tag");
+const annotation_prefix_1 = require("../lang/annotation-prefix");
+// ============================================================================
+// Helpers for the stable (Thrift-derived) wire shape: `Malloy.Annotation[]`.
+//
+// API consumers (render, query-builder, downstream SDKs that target the
+// stable interface) read annotation arrays off projected stable types
+// (`Malloy.Result`, `Malloy.FieldInfo`, etc.) and want low-ceremony reads —
+// no source offsets, no view class. These helpers consume that array shape
+// directly, using the shared `parsePrefix` for route resolution.
+// ============================================================================
+/**
+ * The route a stable {@link Malloy.Annotation} belongs to (`''` for MOTLY
+ * tags, `!` for compiler flags, `myApp` for an app's claimed route, etc.).
+ * Returns `undefined` if the annotation's prefix is malformed.
+ */
+function routeOf(a) {
+    const parsed = (0, annotation_prefix_1.parsePrefix)(a.value);
+    if (parsed.malformation === 'malformed-route')
+        return undefined;
+    return parsed.route;
+}
+/**
+ * The payload of a stable {@link Malloy.Annotation} — the substring after
+ * the prefix and separator (`'name=foo'` for `'#(filter) name=foo'`,
+ * `'tag\n'` for `'# tag\n'` — the lexer keeps the trailing newline).
+ * Returns the empty string for an annotation that has no content.
+ */
+function payloadOf(a) {
+    return a.value.slice((0, annotation_prefix_1.parsePrefix)(a.value).contentIndex);
+}
+/**
+ * Filter `annotations` to just those on `route`, in input order.
+ *
+ * Annotations with `malformed-route` prefixes are excluded (no clean route
+ * to resolve to). `reserved-route` annotations *are* included — their
+ * prefix parses to a real route and the user got a compile-time warning,
+ * but the data is what it is.
+ *
+ * Route filtering is level-blind: `# tag` and `## tag` both resolve to
+ * route `''`. Producers separate object-level from model-level annotations
+ * into different arrays; consumers pass the array carrying the right level.
+ */
+function annotationsForRoute(annotations, route) {
+    if (!annotations)
+        return [];
+    return annotations.filter(a => {
+        const parsed = (0, annotation_prefix_1.parsePrefix)(a.value);
+        return parsed.route === route && parsed.malformation !== 'malformed-route';
+    });
+}
+/**
+ * Parse a stable `Malloy.Annotation[]`'s `route` annotations as MOTLY into
+ * one Tag. The stable counterpart to `Annotations.parseAsTag` — consumes
+ * the flat wire shape, no source offsets. Selection follows
+ * {@link annotationsForRoute} semantics (level-blind, malformed-route
+ * excluded, reserved-route included).
+ */
+function tagFromAnnotations(annotations, route) {
+    const session = new malloy_tag_1.TagParser();
+    for (const a of annotationsForRoute(annotations, route)) {
+        session.parseAnnotation(a.value);
+    }
+    return session.finish();
+}
+//# sourceMappingURL=annotation-utils.js.map

package/dist/api/core.js

@@ -138,7 +138,7 @@ function convertDimension(field) {
     const typeDef = typeDefFromField(field.type);
     return {
         ...(0, model_1.mkFieldDef)(typeDef, field.name),
-        annotation: field.annotations && field.annotations.length
+        annotations: field.annotations && field.annotations.length
             ? {
                 notes: (_a = field.annotations) === null || _a === void 0 ? void 0 : _a.map(a => ({
                     text: a.value,
@@ -505,7 +505,7 @@ function statedCompileQuery(state) {
                 defaultRowLimit: state.defaultRowLimit,
             });
             timer.contribute([sqlTimer.stop()]);
-            const modelAnnotations = (0, to_stable_1.toStableAnnotations)(result.modelDef.annotation);
+            const modelAnnotations = (0, to_stable_1.toStableAnnotations)(result.modelDef.annotations);
             let source;
             if (query.compositeResolvedSourceDef) {
                 source = query.compositeResolvedSourceDef;
@@ -519,7 +519,7 @@ function statedCompileQuery(state) {
                     source = (0, model_1.safeRecordGet)(result.modelDef.contents, query.structRef);
                 }
             }
-            const sourceAnnotations = (0, to_stable_1.toStableAnnotations)(source.annotation);
+            const sourceAnnotations = (0, to_stable_1.toStableAnnotations)(source.annotations);
             const sourceMetadataTag = malloy_tag_1.Tag.withPrefix('#(malloy) ');
             sourceMetadataTag.set(['source', 'name'], translatedQuery.sourceExplore);
             const sourceArguments = (_b = translatedQuery.sourceArguments) !== null && _b !== void 0 ? _b : ((0, model_1.isSourceDef)(source) ? source.arguments : undefined);

package/dist/api/foundation/annotation.d.ts

@@ -0,0 +1,115 @@
+import type { Tag } from '@malloydata/malloy-tag';
+import type { AnnotationsDef, Note, DocumentLocation } from '../../model';
+import type { LogMessage } from '../../lang';
+/**
+ * @deprecated Argument shape for the deprecated RegExp form of
+ * {@link annotationToTag}. The RegExp form cannot see multi-line
+ * annotations (`#|`…`|#`). Pass a route string to `annotationToTag`
+ * instead, or use the {@link Annotations} view on a tagged entity.
+ */
+export interface TagParseSpec {
+    prefix?: RegExp;
+}
+/**
+ * One annotation, returned by {@link Annotations.forRoute} — wraps an IR
+ * note with its parsed route and prefix/content split. Carries the offsets
+ * a caller needs to parse the payload (`.content`) with their own parser
+ * and map parser errors back to source positions.
+ *
+ * Foundation-owned: not derived from the IR `Note` type, so IR can evolve
+ * fields without breaking this public shape. Direct construction is
+ * internal; reach instances via `Annotations.forRoute`.
+ */
+export declare class RoutedNote {
+    private readonly _note;
+    readonly route: string;
+    readonly contentIndex: number;
+    /** @internal */
+    constructor(_note: Note, route: string, contentIndex: number);
+    /** The annotation exactly as written — prefix + content. */
+    get text(): string;
+    /** Where this note starts in source. */
+    get at(): DocumentLocation;
+    /**
+     * Multi-line annotations only (`#|`…`|#`). Number of leading-whitespace
+     * characters stripped from each body line during the dedent pass (Python
+     * `textwrap.dedent` semantics — longest common prefix across non-blank
+     * body lines). Omitted for single-line annotations and for multi-line
+     * annotations with no common indent.
+     *
+     * To map your parser's column numbers back to source:
+     * `source_col = indentStripped + parser_col` for body lines; first-line
+     * columns map straight through, offset by {@link contentIndex}.
+     */
+    get indentStripped(): number | undefined;
+    /** The payload — `text.slice(contentIndex)`. The string to feed to
+     *  your own parser. */
+    get content(): string;
+}
+/**
+ * Collect annotations, using the shared prefix parser.
+ * - no `route`: every annotation, each carrying its own `route` (the only
+ *   way to reach one whose prefix is malformed).
+ * - a `route`: only annotations on that route; malformed prefixes excluded.
+ */
+export declare function collectAnnotations(annote: AnnotationsDef | undefined, route?: string): RoutedNote[];
+/**
+ * @deprecated The RegExp form cannot see multi-line annotations
+ * (`#|`…`|#`). Use `new Annotations(annote).texts(route)` instead, or the
+ * {@link Annotations} view on a tagged entity (`entity.annotations.texts(route)`).
+ */
+export declare function annotationToTaglines(annote: AnnotationsDef | undefined, prefix?: RegExp): string[];
+export interface MalloyTagParse {
+    tag: Tag;
+    log: LogMessage[];
+}
+/** Parse the annotations on `route` (default `''`, the MOTLY tag route) as MOTLY. */
+export declare function annotationToTag(annote: AnnotationsDef | undefined, route?: string): MalloyTagParse;
+/**
+ * @deprecated The RegExp `prefix` form cannot see multi-line annotations
+ * (`#|`…`|#`) and cannot report content offsets for error mapping. Pass a
+ * route string (the other overload), or use {@link Annotations.parseAsTag}
+ * on a tagged entity.
+ */
+export declare function annotationToTag(annote: AnnotationsDef | undefined, spec?: TagParseSpec): MalloyTagParse;
+/**
+ * The route-aware annotation API for a tagged entity.
+ *
+ * An annotation has a *prefix* (everything from `#`/`##` up to the first
+ * whitespace) that resolves to a *route* — a namespace key. Built-in routes:
+ * `''` (MOTLY tags, the human default), `!` (compiler flags), `@` (persistence
+ * directives), `"` (doc-string markdown). Apps stake their own routes with
+ * brackets: `#(myApp) ...` is route `myApp`. The grammar (forms, bracket
+ * pairs, malformation warnings) lives in `lang/prefix.ts`.
+ *
+ * All annotation reading lives here, written once; each tagged class only has
+ * to say *where* its annotation is (by handing it to the constructor). Unlike
+ * the deprecated RegExp readers (`tagParse`/`getTaglines`), this sees multi-
+ * line annotations.
+ */
+export declare class Annotations {
+    private readonly annote;
+    constructor(annote: AnnotationsDef | undefined);
+    /**
+     * Raw annotation text strings (prefix + content) — all routes if `route` is
+     * omitted, just that route's otherwise. The route-based successor to the
+     * deprecated `getTaglines`. For source-mapped offsets (when parsing the
+     * payload with your own parser), see {@link forRoute}.
+     */
+    texts(route?: string): string[];
+    /**
+     * Your route's notes as {@link RoutedNote}s — for callers that parse the
+     * payload with their own parser (instead of MOTLY). Read `.content` to
+     * feed your parser, and `.at` + `.indentStripped` to map your parser's
+     * errors back to source.
+     *
+     * `malformed-route` annotations are excluded (no clean route to resolve
+     * to). `reserved-route` annotations are included — they parse to a real
+     * route and the user got a compile-time warning. Route filtering is
+     * level-blind (`#` and `##` both go to route `''`); the entity hands
+     * you the annotations that apply at its level.
+     */
+    forRoute(route: string): RoutedNote[];
+    /** Parse a route's annotations as a MOTLY tag. Default `''` is the tag route. */
+    parseAsTag(route?: string): MalloyTagParse;
+}

package/dist/{annotation.js → api/foundation/annotation.js}

@@ -1,11 +1,61 @@
 "use strict";
+/*
+ * Copyright Contributors to the Malloy project
+ * SPDX-License-Identifier: MIT
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Annotations = void 0;
+exports.Annotations = exports.RoutedNote = void 0;
 exports.collectAnnotations = collectAnnotations;
 exports.annotationToTaglines = annotationToTaglines;
 exports.annotationToTag = annotationToTag;
 const malloy_tag_1 = require("@malloydata/malloy-tag");
-const prefix_1 = require("./prefix");
+const annotation_prefix_1 = require("../../lang/annotation-prefix");
+/**
+ * One annotation, returned by {@link Annotations.forRoute} — wraps an IR
+ * note with its parsed route and prefix/content split. Carries the offsets
+ * a caller needs to parse the payload (`.content`) with their own parser
+ * and map parser errors back to source positions.
+ *
+ * Foundation-owned: not derived from the IR `Note` type, so IR can evolve
+ * fields without breaking this public shape. Direct construction is
+ * internal; reach instances via `Annotations.forRoute`.
+ */
+class RoutedNote {
+    /** @internal */
+    constructor(_note, route, contentIndex) {
+        this._note = _note;
+        this.route = route;
+        this.contentIndex = contentIndex;
+    }
+    /** The annotation exactly as written — prefix + content. */
+    get text() {
+        return this._note.text;
+    }
+    /** Where this note starts in source. */
+    get at() {
+        return this._note.at;
+    }
+    /**
+     * Multi-line annotations only (`#|`…`|#`). Number of leading-whitespace
+     * characters stripped from each body line during the dedent pass (Python
+     * `textwrap.dedent` semantics — longest common prefix across non-blank
+     * body lines). Omitted for single-line annotations and for multi-line
+     * annotations with no common indent.
+     *
+     * To map your parser's column numbers back to source:
+     * `source_col = indentStripped + parser_col` for body lines; first-line
+     * columns map straight through, offset by {@link contentIndex}.
+     */
+    get indentStripped() {
+        return this._note.indentStripped;
+    }
+    /** The payload — `text.slice(contentIndex)`. The string to feed to
+     *  your own parser. */
+    get content() {
+        return this._note.text.slice(this.contentIndex);
+    }
+}
+exports.RoutedNote = RoutedNote;
 /** Every Note of an annotation, inherited first, in document order. */
 function* notesInOrder(annote) {
     if (annote.inherits)
@@ -15,35 +65,28 @@ function* notesInOrder(annote) {
     if (annote.notes)
         yield* annote.notes;
 }
+/**
+ * Collect annotations, using the shared prefix parser.
+ * - no `route`: every annotation, each carrying its own `route` (the only
+ *   way to reach one whose prefix is malformed).
+ * - a `route`: only annotations on that route; malformed prefixes excluded.
+ */
 function collectAnnotations(annote, route) {
-    if (route === undefined) {
-        return Array.from(notesInOrder(annote !== null && annote !== void 0 ? annote : {}), note => {
-            const { route: noteRoute, contentIndex } = (0, prefix_1.parsePrefix)(note.text);
-            return {
-                rawText: note.text,
-                contentIndex,
-                at: note.at,
-                route: noteRoute,
-                indentStripped: note.indentStripped,
-            };
-        });
-    }
     const matching = [];
     for (const note of notesInOrder(annote !== null && annote !== void 0 ? annote : {})) {
-        const parsed = (0, prefix_1.parsePrefix)(note.text);
-        if (parsed.route === route && parsed.malformation !== 'malformed-route') {
-            matching.push({
-                rawText: note.text,
-                contentIndex: parsed.contentIndex,
-                at: note.at,
-                indentStripped: note.indentStripped,
-            });
+        const parsed = (0, annotation_prefix_1.parsePrefix)(note.text);
+        if (route === undefined) {
+            matching.push(new RoutedNote(note, parsed.route, parsed.contentIndex));
+        }
+        else if (parsed.route === route &&
+            parsed.malformation !== 'malformed-route') {
+            matching.push(new RoutedNote(note, parsed.route, parsed.contentIndex));
         }
     }
     return matching;
 }
 /**
- * Collect all matching Notes from an Annotation, walking the inherits
+ * Collect all matching Notes from an AnnotationsDef, walking the inherits
  * chain. Returns notes in inheritance order (inherited first).
  *
  * @deprecated RegExp prefix matching; use {@link collectAnnotations} with a route.
@@ -53,9 +96,9 @@ function collectNotes(annote, prefix) {
     return prefix ? notes.filter(note => note.text.match(prefix)) : notes;
 }
 /**
- * @deprecated The RegExp form cannot see block annotations (`#|`…`|#`). Use
- * `new Annotations(annote).texts(route)` instead, or the {@link Annotations}
- * view on a tagged entity (`entity.annotations.texts(route)`).
+ * @deprecated The RegExp form cannot see multi-line annotations
+ * (`#|`…`|#`). Use `new Annotations(annote).texts(route)` instead, or the
+ * {@link Annotations} view on a tagged entity (`entity.annotations.texts(route)`).
  */
 function annotationToTaglines(annote, prefix) {
     return collectNotes(annote || {}, prefix).map(n => n.text);
@@ -90,7 +133,7 @@ function annotationToTag(annote, arg) {
     }
     const matched = collectAnnotations(annote, arg !== null && arg !== void 0 ? arg : '');
     return parseTaglines(matched.map(a => ({
-        text: a.rawText,
+        text: a.text,
         at: a.at,
         indentStripped: a.indentStripped,
     })));
@@ -103,12 +146,12 @@ function annotationToTag(annote, arg) {
  * `''` (MOTLY tags, the human default), `!` (compiler flags), `@` (persistence
  * directives), `"` (doc-string markdown). Apps stake their own routes with
  * brackets: `#(myApp) ...` is route `myApp`. The grammar (forms, bracket
- * pairs, malformation warnings) lives in `./prefix.ts`.
+ * pairs, malformation warnings) lives in `lang/prefix.ts`.
  *
  * All annotation reading lives here, written once; each tagged class only has
  * to say *where* its annotation is (by handing it to the constructor). Unlike
- * the deprecated RegExp readers (`tagParse`/`getTaglines`), this sees block
- * annotations.
+ * the deprecated RegExp readers (`tagParse`/`getTaglines`), this sees multi-
+ * line annotations.
  */
 class Annotations {
     constructor(annote) {
@@ -117,21 +160,23 @@ class Annotations {
     /**
      * Raw annotation text strings (prefix + content) — all routes if `route` is
      * omitted, just that route's otherwise. The route-based successor to the
-     * deprecated `getTaglines`. For source-mapped offsets (bring-your-own
-     * parsers), see {@link forRoute}.
+     * deprecated `getTaglines`. For source-mapped offsets (when parsing the
+     * payload with your own parser), see {@link forRoute}.
      */
     texts(route) {
-        const items = route === undefined
-            ? collectAnnotations(this.annote)
-            : collectAnnotations(this.annote, route);
-        return items.map(a => a.rawText);
+        return collectAnnotations(this.annote, route).map(a => a.text);
     }
     /**
-     * Your route's annotations as objects (`rawText` + `contentIndex` + `at`) —
-     * the bring-your-own-parser door. A non-MOTLY app (e.g. JSON on its own
-     * route) reads these to slice the content (`rawText.slice(contentIndex)`)
-     * itself and map its parser's errors back to source via `at`. Malformed-prefix
-     * annotations are excluded.
+     * Your route's notes as {@link RoutedNote}s — for callers that parse the
+     * payload with their own parser (instead of MOTLY). Read `.content` to
+     * feed your parser, and `.at` + `.indentStripped` to map your parser's
+     * errors back to source.
+     *
+     * `malformed-route` annotations are excluded (no clean route to resolve
+     * to). `reserved-route` annotations are included — they parse to a real
+     * route and the user got a compile-time warning. Route filtering is
+     * level-blind (`#` and `##` both go to route `''`); the entity hands
+     * you the annotations that apply at its level.
      */
     forRoute(route) {
         return collectAnnotations(this.annote, route);
@@ -169,7 +214,7 @@ function mapMalloyError(e, note) {
 /** Length of the annotation prefix per malloy-tag's `stripPrefix`: index of
  *  the first whitespace, or 0 if none. */
 function prefixLength(text) {
-    const { contentIndex } = (0, prefix_1.parsePrefix)(text);
+    const { contentIndex } = (0, annotation_prefix_1.parsePrefix)(text);
     return contentIndex === text.length ? 0 : contentIndex - 1;
 }
 //# sourceMappingURL=annotation.js.map

package/dist/api/foundation/compile.js

@@ -250,7 +250,7 @@ class Malloy {
                         }
                     }
                 }
-                const { modelAnnotation } = translator.modelAnnotation(model === null || model === void 0 ? void 0 : model._modelDef);
+                const { modelAnnotations } = translator.modelAnnotation(model === null || model === void 0 ? void 0 : model._modelDef);
                 if (result.tables) {
                     // collect tables by connection name since there may be multiple connections
                     const tablesByConnection = new Map();
@@ -273,7 +273,7 @@ class Malloy {
                             //      the translator runs into an infinite loop fetching tables.
                             const { schemas: tables, errors } = await Malloy.safelyFetchTableSchema(connection, tablePathByKey, {
                                 refreshTimestamp,
-                                modelAnnotation,
+                                modelAnnotations,
                             });
                             translator.update({ tables, errors: { tables: errors } });
                         }
@@ -318,7 +318,7 @@ class Malloy {
                         const conn = await connections.lookupConnection(connectionName);
                         const resolved = await conn.fetchSchemaForSQLStruct(toCompile, {
                             refreshTimestamp,
-                            modelAnnotation,
+                            modelAnnotations,
                         });
                         if (resolved.error) {
                             translator.update({

package/dist/api/foundation/core.d.ts

@@ -1,13 +1,13 @@
 import type { LogMessage } from '../../lang';
-import type { BuildID, CompiledQuery, ConstantExpr, DocumentLocation, BooleanFieldDef, JSONFieldDef, NumberFieldDef, StringFieldDef, FilterCondition, Given as InternalGiven, GivenID, GivenTypeDef, Query as InternalQuery, ModelDef, DocumentPosition as ModelDocumentPosition, NamedQueryDef, StructDef, TurtleDef, NativeUnsupportedFieldDef, ImportLocation, Annotation, NamedModelObject, AtomicFieldDef, DateFieldDef, ATimestampFieldDef, SourceDef, Argument, SourceComponentInfo, DocumentReference, PersistableSourceDef } from '../../model';
+import type { BuildID, CompiledQuery, ConstantExpr, DocumentLocation, BooleanFieldDef, JSONFieldDef, NumberFieldDef, StringFieldDef, FilterCondition, Given as InternalGiven, GivenID, GivenTypeDef, Query as InternalQuery, ModelDef, DocumentPosition as ModelDocumentPosition, NamedQueryDef, StructDef, TurtleDef, NativeUnsupportedFieldDef, ImportLocation, AnnotationsDef, NamedModelObject, AtomicFieldDef, DateFieldDef, ATimestampFieldDef, SourceDef, Argument, SourceComponentInfo, DocumentReference, PersistableSourceDef } from '../../model';
 import { QueryModel } from '../../model';
 import type { Dialect } from '../../dialect';
 import type { BuildGraph, CompileQueryOptions } from './types';
 import { Tag } from '@malloydata/malloy-tag';
-import type { MalloyTagParse, TagParseSpec } from '../../annotation';
-import { Annotations } from '../../annotation';
+import type { MalloyTagParse, TagParseSpec } from './annotation';
+import { Annotations } from './annotation';
 import type * as Malloy from '@malloydata/malloy-interfaces';
-import type { Taggable } from '../../taggable';
+import type { Taggable } from './taggable';
 declare abstract class Entity {
     private readonly _name;
     protected readonly _parent?: Explore;
@@ -100,7 +100,9 @@ export declare class Explore extends Entity implements Taggable {
     get source(): Explore | undefined;
     isIntrinsic(): boolean;
     isExploreField(): this is ExploreField;
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec?: TagParseSpec): MalloyTagParse;
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix?: RegExp): string[];
     get annotations(): Annotations;
     private parsedModelTag?;
@@ -141,7 +143,9 @@ export declare class AtomicField extends Entity implements Taggable {
     protected parent: Explore;
     constructor(fieldTypeDef: AtomicFieldDef, parent: Explore, source?: AtomicField);
     get type(): AtomicFieldType;
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec?: TagParseSpec): MalloyTagParse;
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix?: RegExp): string[];
     get annotations(): Annotations;
     isIntrinsic(): boolean;
@@ -209,7 +213,9 @@ export declare class Query extends Entity {
 export declare class QueryField extends Query implements Taggable {
     protected parent: Explore;
     constructor(turtleDef: TurtleDef, parent: Explore, source?: Query);
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec?: TagParseSpec): MalloyTagParse;
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix?: RegExp): string[];
     get annotations(): Annotations;
     isQueryField(): this is QueryField;
@@ -250,6 +256,40 @@ export interface RuntimeContext {
      *  introspection-driven UIs don't render editors for them. */
     readonly finalizedGivens?: ReadonlySet<string>;
 }
+export type ReferenceKind = 'field' | 'join' | 'explore' | 'query' | 'sqlBlock' | 'given';
+/**
+ * A reference to a definition found at a position in a Malloy document —
+ * the Foundation view returned by {@link Model.referenceAt}. Carries the
+ * use-site location (where the reference appears), the definition's
+ * location (where to go for "go to definition"), the kind of entity
+ * referenced, and an `annotations` view over the definition's annotations.
+ *
+ * Construct via {@link Model.referenceAt}; direct construction is internal.
+ */
+export declare class Reference {
+    private readonly _ref;
+    /** @internal */
+    constructor(_ref: DocumentReference);
+    /** The name as written at the use site (e.g. `"orders"`). */
+    get text(): string;
+    /** What kind of entity this reference points at. */
+    get kind(): ReferenceKind;
+    /** Where this reference appears in source. */
+    get location(): DocumentLocation;
+    /** Where the definition is. Omitted for synthetic references that have
+     *  no source-level definition site. */
+    get definitionLocation(): DocumentLocation | undefined;
+    /** The referent's type as a string (e.g. `"string"` for a string field,
+     *  `"source"` for a source). Free-form text from the IR; used by IDE
+     *  display to render type hints. */
+    get definitionType(): string;
+    /** For given references only: the textual form of the given's default
+     *  expression, if one was declared. Undefined for non-given references
+     *  and for givens without a default. */
+    get defaultText(): string | undefined;
+    /** The definition's annotations, as a view. */
+    get annotations(): Annotations;
+}
 export declare class Model implements Taggable {
     private modelDef;
     readonly problems: LogMessage[];
@@ -285,15 +325,23 @@ export declare class Model implements Taggable {
      * every given the model can accept.
      */
     get givens(): ReadonlyMap<string, Given>;
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec?: TagParseSpec): MalloyTagParse;
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix?: RegExp): string[];
     get annotations(): Annotations;
     /**
-     * Retrieve a document reference for the token at the given position within
-     * the document that produced this model.
+     * Retrieve a reference for the token at the given position within the
+     * document that produced this model.
      *
      * @param position A position within the document.
-     * @return A `DocumentReference` at that position if one exists.
+     * @return A {@link Reference} at that position if one exists.
+     */
+    referenceAt(position: ModelDocumentPosition): Reference | undefined;
+    /**
+     * @deprecated Use {@link referenceAt} — returns a Foundation
+     * {@link Reference} view instead of the raw IR. This method returns
+     * the IR shape directly and will be removed in a future release.
      */
     getReference(position: ModelDocumentPosition): DocumentReference | undefined;
     /**
@@ -414,16 +462,14 @@ export declare class PersistSource implements Taggable {
      */
     get _explore(): Explore;
     /**
-     * The annotation on this source.
-     */
-    get annotation(): Annotation | undefined;
-    /**
-     * Parse the source's tags.
+     * @deprecated Hands out raw IR (`AnnotationsDef`). Use `.annotations`
+     * (returns the {@link Annotations} view). Slated for removal once
+     * external consumers migrate.
      */
+    get annotation(): AnnotationsDef | undefined;
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec?: TagParseSpec): MalloyTagParse;
-    /**
-     * Get annotation taglines matching an optional prefix.
-     */
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix?: RegExp): string[];
     get annotations(): Annotations;
     /**
@@ -489,7 +535,9 @@ export declare class Given implements Taggable {
     /** `undefined` when no default — the caller must supply at run time. */
     get default(): ConstantExpr | undefined;
     get location(): DocumentLocation | undefined;
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec?: TagParseSpec): MalloyTagParse;
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix?: RegExp): string[];
     get annotations(): Annotations;
 }
@@ -500,7 +548,9 @@ export declare class PreparedQuery implements Taggable {
     _query: InternalQuery | NamedQueryDef;
     constructor(query: InternalQuery, _model: Model, problems: LogMessage[], name?: string | undefined);
     get _modelDef(): ModelDef;
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec?: TagParseSpec): MalloyTagParse;
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix?: RegExp): string[];
     get annotations(): Annotations;
     /**
@@ -544,11 +594,24 @@ export declare class PreparedResult implements Taggable {
     protected inner: CompiledQuery;
     constructor(query: CompiledQuery, modelDef: ModelDef);
     static fromJson({ query, modelDef, }: PreparedResultJSON): PreparedResult;
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec?: TagParseSpec): MalloyTagParse;
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix?: RegExp): string[];
     get annotations(): Annotations;
-    get annotation(): Annotation | undefined;
-    get modelAnnotation(): Annotation | undefined;
+    /**
+     * @deprecated Hands out raw IR (`AnnotationsDef`). Use `.annotations`
+     * (returns the {@link Annotations} view) for read access. Internal
+     * code that needs the IR shape should read `._rawQuery.annotations`
+     * directly. Slated for removal once external consumers migrate.
+     */
+    get annotation(): AnnotationsDef | undefined;
+    /**
+     * @deprecated Hands out raw IR (`AnnotationsDef`). Internal code that
+     * needs the model-level IR shape should read `._modelDef.annotations`
+     * directly. Slated for removal once external consumers migrate.
+     */
+    get modelAnnotation(): AnnotationsDef | undefined;
     get modelTag(): Tag;
     /**
      * @return The name of the connection this query should be run against.