@malloydata/malloy 0.0.399 → 0.0.401

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, Pipeline, 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;
@@ -90,6 +90,16 @@ export type PreparedResultJSON = {
     query: CompiledQuery;
     modelDef: ModelDef;
 };
+/**
+ * Identifier-only enumeration of a model's top-level queries.
+ * Internal: returned by `Model.queries()`, not exported. Callers pair
+ * the names with `getPreparedQueryByName` and the indices `0..unnamed-1`
+ * with `getPreparedQueryByIndex` to load any one of them.
+ */
+interface ModelQueries {
+    named: string[];
+    unnamed: number;
+}
 export declare class Explore extends Entity implements Taggable {
     protected readonly _structDef: StructDef;
     protected readonly _parentExplore?: Explore;
@@ -100,7 +110,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 +153,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;
@@ -198,20 +212,22 @@ export declare class StringField extends AtomicField {
     private fieldStringDef;
     constructor(fieldStringDef: StringFieldDef, parent: Explore, source?: AtomicField);
 }
-export declare class Query extends Entity {
+export declare class Query extends Entity implements Taggable {
     protected turtleDef: TurtleDef;
     private sourceQuery?;
     constructor(turtleDef: TurtleDef, parent?: Explore, source?: Query);
     get source(): Query | undefined;
     isIntrinsic(): boolean;
     get location(): DocumentLocation | undefined;
-}
-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;
+}
+export declare class QueryField extends Query {
+    protected parent: Explore;
+    constructor(turtleDef: TurtleDef, parent: Explore, source?: Query);
     isQueryField(): this is QueryField;
     isExploreField(): this is ExploreField;
     isAtomicField(): this is AtomicField;
@@ -250,6 +266,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 +335,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;
     /**
@@ -344,9 +402,18 @@ export declare class Model implements Taggable {
      */
     get explores(): Explore[];
     /**
-     * Get an array of `NamedQueryDef`s contained in the model.
+     * Enumerate the model's top-level queries by identifier.
      *
-     * @return An array of `NamedQueryDef`s contained in the model.
+     * Returns the names of named queries (`query: foo is ...`) and the count
+     * of unnamed `run:` statements. Pair with {@link getPreparedQueryByName}
+     * and {@link getPreparedQueryByIndex} to load any of them — those are the
+     * only path to the query itself; this getter exposes only identifiers,
+     * not IR.
+     */
+    queries(): ModelQueries;
+    /**
+     * @deprecated Leaks IR. Use {@link queries} for enumeration and
+     *   {@link getPreparedQueryByName} to load a named query.
      */
     get namedQueries(): NamedQueryDef[];
     get exportedExplores(): Explore[];
@@ -414,16 +481,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,20 +554,35 @@ 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;
 }
-export declare class PreparedQuery implements Taggable {
+/**
+ * Internal abstract base for Foundation wrappers around an IR `Pipeline`
+ * (an IR object that has a pipeline, annotations, and a source location).
+ * Owns the four `Taggable` accessors and a `location` getter, all reading
+ * from the wrapped IR. Not exported.
+ */
+declare abstract class PipelineBase implements Taggable {
+    protected pipelineDef: Pipeline;
+    constructor(pipelineDef: Pipeline);
+    get annotations(): Annotations;
+    get location(): DocumentLocation | undefined;
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
+    tagParse(spec?: TagParseSpec): MalloyTagParse;
+    /** @deprecated Use `.annotations.texts(route)`. */
+    getTaglines(prefix?: RegExp): string[];
+}
+export declare class PreparedQuery extends PipelineBase {
     private _model;
     problems: LogMessage[];
     name?: string | undefined;
-    _query: InternalQuery | NamedQueryDef;
     constructor(query: InternalQuery, _model: Model, problems: LogMessage[], name?: string | undefined);
+    get _query(): InternalQuery | NamedQueryDef;
     get _modelDef(): ModelDef;
-    tagParse(spec?: TagParseSpec): MalloyTagParse;
-    getTaglines(prefix?: RegExp): string[];
-    get annotations(): Annotations;
     /**
      * Generate the SQL for this query.
      *
@@ -544,11 +624,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.

package/dist/api/foundation/core.js

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: MIT
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PreparedResult = exports.PreparedQuery = exports.Given = exports.PersistSource = exports.Model = exports.ExploreField = exports.QueryField = exports.Query = exports.StringField = exports.UnsupportedField = exports.JSONField = exports.BooleanField = exports.NumberField = exports.TimestampField = exports.DateField = exports.AtomicField = exports.Explore = exports.JoinRelationship = exports.TimestampTimeframe = exports.DateTimeframe = exports.AtomicFieldType = exports.SourceRelationship = void 0;
+exports.PreparedResult = exports.PreparedQuery = exports.Given = exports.PersistSource = exports.Model = exports.Reference = exports.ExploreField = exports.QueryField = exports.Query = exports.StringField = exports.UnsupportedField = exports.JSONField = exports.BooleanField = exports.NumberField = exports.TimestampField = exports.DateField = exports.AtomicField = exports.Explore = exports.JoinRelationship = exports.TimestampTimeframe = exports.DateTimeframe = exports.AtomicFieldType = exports.SourceRelationship = void 0;
 const model_1 = require("../../model");
 const utils_1 = require("../../model/utils");
 const dialect_1 = require("../../dialect");
@@ -12,7 +12,7 @@ const persist_utils_1 = require("../../model/persist_utils");
 const source_def_utils_1 = require("../../model/source_def_utils");
 const given_binding_1 = require("../../model/given_binding");
 const malloy_tag_1 = require("@malloydata/malloy-tag");
-const annotation_1 = require("../../annotation");
+const annotation_1 = require("./annotation");
 const to_stable_1 = require("../../to_stable");
 const util_1 = require("../util");
 const utils_2 = require("../../lang/utils");
@@ -148,17 +148,19 @@ class Explore extends Entity {
     isExploreField() {
         return false;
     }
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec) {
-        return (0, annotation_1.annotationToTag)(this._structDef.annotation, spec);
+        return (0, annotation_1.annotationToTag)(this._structDef.annotations, spec);
     }
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix) {
-        return (0, annotation_1.annotationToTaglines)(this._structDef.annotation, prefix);
+        return (0, annotation_1.annotationToTaglines)(this._structDef.annotations, prefix);
     }
     get annotations() {
-        return new annotation_1.Annotations(this._structDef.annotation);
+        return new annotation_1.Annotations(this._structDef.annotations);
     }
     get modelTag() {
-        this.parsedModelTag || (this.parsedModelTag = new annotation_1.Annotations(this._structDef.modelAnnotation).parseAsTag().tag);
+        this.parsedModelTag || (this.parsedModelTag = new annotation_1.Annotations(this._structDef.modelAnnotations).parseAsTag().tag);
         return this.parsedModelTag;
     }
     /**
@@ -462,14 +464,16 @@ class AtomicField extends Entity {
             }
         }
     }
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec) {
-        return (0, annotation_1.annotationToTag)(this.fieldTypeDef.annotation, spec);
+        return (0, annotation_1.annotationToTag)(this.fieldTypeDef.annotations, spec);
     }
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix) {
-        return (0, annotation_1.annotationToTaglines)(this.fieldTypeDef.annotation, prefix);
+        return (0, annotation_1.annotationToTaglines)(this.fieldTypeDef.annotations, prefix);
     }
     get annotations() {
-        return new annotation_1.Annotations(this.fieldTypeDef.annotation);
+        return new annotation_1.Annotations(this.fieldTypeDef.annotations);
     }
     isIntrinsic() {
         return (0, model_1.fieldIsIntrinsic)(this.fieldTypeDef);
@@ -659,6 +663,17 @@ class Query extends Entity {
     get location() {
         return this.turtleDef.location;
     }
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
+    tagParse(spec) {
+        return (0, annotation_1.annotationToTag)(this.turtleDef.annotations, spec);
+    }
+    /** @deprecated Use `.annotations.texts(route)`. */
+    getTaglines(prefix) {
+        return (0, annotation_1.annotationToTaglines)(this.turtleDef.annotations, prefix);
+    }
+    get annotations() {
+        return new annotation_1.Annotations(this.turtleDef.annotations);
+    }
 }
 exports.Query = Query;
 class QueryField extends Query {
@@ -666,15 +681,6 @@ class QueryField extends Query {
         super(turtleDef, parent, source);
         this.parent = parent;
     }
-    tagParse(spec) {
-        return (0, annotation_1.annotationToTag)(this.turtleDef.annotation, spec);
-    }
-    getTaglines(prefix) {
-        return (0, annotation_1.annotationToTaglines)(this.turtleDef.annotation, prefix);
-    }
-    get annotations() {
-        return new annotation_1.Annotations(this.turtleDef.annotation);
-    }
     isQueryField() {
         return true;
     }
@@ -726,10 +732,10 @@ class ExploreField extends Explore {
         return this.joinRelationship !== JoinRelationship.OneToOne;
     }
     tagParse(spec) {
-        return (0, annotation_1.annotationToTag)(this._structDef.annotation, spec);
+        return (0, annotation_1.annotationToTag)(this._structDef.annotations, spec);
     }
     get annotations() {
-        return new annotation_1.Annotations(this._structDef.annotation);
+        return new annotation_1.Annotations(this._structDef.annotations);
     }
     isQueryField() {
         return false;
@@ -755,6 +761,66 @@ class ExploreField extends Explore {
     }
 }
 exports.ExploreField = ExploreField;
+const REFERENCE_KIND_BY_IR_TYPE = {
+    fieldReference: 'field',
+    joinReference: 'join',
+    exploreReference: 'explore',
+    queryReference: 'query',
+    sqlBlockReference: 'sqlBlock',
+    givenReference: '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.
+ */
+class Reference {
+    /** @internal */
+    constructor(_ref) {
+        this._ref = _ref;
+    }
+    /** The name as written at the use site (e.g. `"orders"`). */
+    get text() {
+        return this._ref.text;
+    }
+    /** What kind of entity this reference points at. */
+    get kind() {
+        return REFERENCE_KIND_BY_IR_TYPE[this._ref.type];
+    }
+    /** Where this reference appears in source. */
+    get location() {
+        return this._ref.location;
+    }
+    /** Where the definition is. Omitted for synthetic references that have
+     *  no source-level definition site. */
+    get definitionLocation() {
+        return this._ref.definition.location;
+    }
+    /** 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() {
+        return this._ref.definition.type;
+    }
+    /** 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() {
+        if (this._ref.type === 'givenReference') {
+            return this._ref.definition.defaultText;
+        }
+        return undefined;
+    }
+    /** The definition's annotations, as a view. */
+    get annotations() {
+        return new annotation_1.Annotations(this._ref.definition.annotations);
+    }
+}
+exports.Reference = Reference;
 class Model {
     constructor(modelDef, problems, fromSources, existingQueryModel, 
     /**
@@ -813,21 +879,32 @@ class Model {
         }
         return out;
     }
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec) {
-        return (0, annotation_1.annotationToTag)(this.modelDef.annotation, spec);
+        return (0, annotation_1.annotationToTag)(this.modelDef.annotations, spec);
     }
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix) {
-        return (0, annotation_1.annotationToTaglines)(this.modelDef.annotation, prefix);
+        return (0, annotation_1.annotationToTaglines)(this.modelDef.annotations, prefix);
     }
     get annotations() {
-        return new annotation_1.Annotations(this.modelDef.annotation);
+        return new annotation_1.Annotations(this.modelDef.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) {
+        const ref = this.references.find(position);
+        return ref ? new Reference(ref) : 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) {
         return this.references.find(position);
@@ -914,9 +991,26 @@ class Model {
             .map(structDef => new Explore(structDef));
     }
     /**
-     * Get an array of `NamedQueryDef`s contained in the model.
+     * Enumerate the model's top-level queries by identifier.
      *
-     * @return An array of `NamedQueryDef`s contained in the model.
+     * Returns the names of named queries (`query: foo is ...`) and the count
+     * of unnamed `run:` statements. Pair with {@link getPreparedQueryByName}
+     * and {@link getPreparedQueryByIndex} to load any of them — those are the
+     * only path to the query itself; this getter exposes only identifiers,
+     * not IR.
+     */
+    queries() {
+        const named = [];
+        for (const object of Object.values(this.modelDef.contents)) {
+            if (object.type === 'query') {
+                named.push(object.name);
+            }
+        }
+        return { named, unnamed: this.modelDef.queryList.length };
+    }
+    /**
+     * @deprecated Leaks IR. Use {@link queries} for enumeration and
+     *   {@link getPreparedQueryByName} to load a named query.
      */
     get namedQueries() {
         const isNamedQueryDef = (object) => object.type === 'query';
@@ -1055,20 +1149,18 @@ class PersistSource {
         return this.explore;
     }
     /**
-     * The annotation on this source.
+     * @deprecated Hands out raw IR (`AnnotationsDef`). Use `.annotations`
+     * (returns the {@link Annotations} view). Slated for removal once
+     * external consumers migrate.
      */
     get annotation() {
-        return this.persistableDef.annotation;
+        return this.persistableDef.annotations;
     }
-    /**
-     * Parse the source's tags.
-     */
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec) {
         return this.explore.tagParse(spec);
     }
-    /**
-     * Get annotation taglines matching an optional prefix.
-     */
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix) {
         return this.explore.getTaglines(prefix);
     }
@@ -1171,36 +1263,57 @@ class Given {
     get location() {
         return this._internal.location;
     }
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec) {
-        return (0, annotation_1.annotationToTag)(this._internal.annotation, spec);
+        return (0, annotation_1.annotationToTag)(this._internal.annotations, spec);
     }
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix) {
-        return (0, annotation_1.annotationToTaglines)(this._internal.annotation, prefix);
+        return (0, annotation_1.annotationToTaglines)(this._internal.annotations, prefix);
     }
     get annotations() {
-        return new annotation_1.Annotations(this._internal.annotation);
+        return new annotation_1.Annotations(this._internal.annotations);
     }
 }
 exports.Given = Given;
-class PreparedQuery {
+/**
+ * Internal abstract base for Foundation wrappers around an IR `Pipeline`
+ * (an IR object that has a pipeline, annotations, and a source location).
+ * Owns the four `Taggable` accessors and a `location` getter, all reading
+ * from the wrapped IR. Not exported.
+ */
+class PipelineBase {
+    constructor(pipelineDef) {
+        this.pipelineDef = pipelineDef;
+    }
+    get annotations() {
+        return new annotation_1.Annotations(this.pipelineDef.annotations);
+    }
+    get location() {
+        return this.pipelineDef.location;
+    }
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
+    tagParse(spec) {
+        return (0, annotation_1.annotationToTag)(this.pipelineDef.annotations, spec);
+    }
+    /** @deprecated Use `.annotations.texts(route)`. */
+    getTaglines(prefix) {
+        return (0, annotation_1.annotationToTaglines)(this.pipelineDef.annotations, prefix);
+    }
+}
+class PreparedQuery extends PipelineBase {
     constructor(query, _model, problems, name) {
+        super(query);
         this._model = _model;
         this.problems = problems;
         this.name = name;
-        this._query = query;
+    }
+    get _query() {
+        return this.pipelineDef;
     }
     get _modelDef() {
         return this._model._modelDef;
     }
-    tagParse(spec) {
-        return (0, annotation_1.annotationToTag)(this._query.annotation, spec);
-    }
-    getTaglines(prefix) {
-        return (0, annotation_1.annotationToTaglines)(this._query.annotation, prefix);
-    }
-    get annotations() {
-        return new annotation_1.Annotations(this._query.annotation);
-    }
     /**
      * Generate the SQL for this query.
      *
@@ -1299,23 +1412,36 @@ class PreparedResult {
         }
         return new PreparedResult(query, modelDef);
     }
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec) {
-        return (0, annotation_1.annotationToTag)(this.inner.annotation, spec);
+        return (0, annotation_1.annotationToTag)(this.inner.annotations, spec);
     }
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix) {
-        return (0, annotation_1.annotationToTaglines)(this.inner.annotation, prefix);
+        return (0, annotation_1.annotationToTaglines)(this.inner.annotations, prefix);
     }
     get annotations() {
-        return new annotation_1.Annotations(this.inner.annotation);
+        return new annotation_1.Annotations(this.inner.annotations);
     }
+    /**
+     * @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() {
-        return this.inner.annotation;
+        return this.inner.annotations;
     }
+    /**
+     * @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() {
-        return this.modelDef.annotation;
+        return this.modelDef.annotations;
     }
     get modelTag() {
-        return new annotation_1.Annotations(this.modelDef.annotation).parseAsTag().tag;
+        return new annotation_1.Annotations(this.modelDef.annotations).parseAsTag().tag;
     }
     /**
      * @return The name of the connection this query should be run against.
@@ -1346,7 +1472,7 @@ class PreparedResult {
         const explore = this.inner.structs[this.inner.structs.length - 1];
         const namedExplore = {
             ...explore,
-            annotation: this.inner.annotation,
+            annotations: this.inner.annotations,
             name: this.inner.queryName || explore.name,
         };
         try {
@@ -1388,7 +1514,7 @@ class PreparedResult {
         const structs = this.inner.structs;
         const struct = structs[structs.length - 1];
         const schema = { fields: (0, to_stable_1.convertFieldInfos)(struct, struct.fields) };
-        const annotations = (0, to_stable_1.toStableAnnotations)(this.inner.annotation);
+        const annotations = (0, to_stable_1.toStableAnnotations)(this.inner.annotations);
         const metadataAnnot = struct.resultMetadata
             ? (0, to_stable_1.getResultStructMetadataAnnotation)(struct, struct.resultMetadata)
             : undefined;
@@ -1417,7 +1543,7 @@ class PreparedResult {
                 .set(['query_name'], this.inner.queryName || struct.name)
                 .toString(),
         });
-        const modelAnnotations = (0, to_stable_1.toStableAnnotations)(this.modelDef.annotation);
+        const modelAnnotations = (0, to_stable_1.toStableAnnotations)(this.modelDef.annotations);
         return {
             schema,
             data,