@malloydata/malloy 0.0.398 → 0.0.400

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);
@@ -666,14 +670,16 @@ class QueryField extends Query {
         super(turtleDef, parent, source);
         this.parent = parent;
     }
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec) {
-        return (0, annotation_1.annotationToTag)(this.turtleDef.annotation, spec);
+        return (0, annotation_1.annotationToTag)(this.turtleDef.annotations, spec);
     }
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix) {
-        return (0, annotation_1.annotationToTaglines)(this.turtleDef.annotation, prefix);
+        return (0, annotation_1.annotationToTaglines)(this.turtleDef.annotations, prefix);
     }
     get annotations() {
-        return new annotation_1.Annotations(this.turtleDef.annotation);
+        return new annotation_1.Annotations(this.turtleDef.annotations);
     }
     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);
@@ -1055,20 +1132,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,14 +1246,16 @@ 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;
@@ -1192,14 +1269,16 @@ class PreparedQuery {
     get _modelDef() {
         return this._model._modelDef;
     }
+    /** @deprecated Use `.annotations.parseAsTag(route)`. */
     tagParse(spec) {
-        return (0, annotation_1.annotationToTag)(this._query.annotation, spec);
+        return (0, annotation_1.annotationToTag)(this._query.annotations, spec);
     }
+    /** @deprecated Use `.annotations.texts(route)`. */
     getTaglines(prefix) {
-        return (0, annotation_1.annotationToTaglines)(this._query.annotation, prefix);
+        return (0, annotation_1.annotationToTaglines)(this._query.annotations, prefix);
     }
     get annotations() {
-        return new annotation_1.Annotations(this._query.annotation);
+        return new annotation_1.Annotations(this._query.annotations);
     }
     /**
      * Generate the SQL for this query.
@@ -1299,23 +1378,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 +1438,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 +1480,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 +1509,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,

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

@@ -4,7 +4,7 @@ export { EmptyURLReader, InMemoryURLReader, FixedConnectionMap, hashForInvalidat
 export type { ModelCache, CachedModel } from './cache';
 export { CacheManager, InMemoryModelCache } from './cache';
 export { Parse, DocumentTablePath, DocumentRange, DocumentPosition, DocumentSymbol, DocumentCompletion, } from './document';
-export { SourceRelationship, AtomicFieldType, DateTimeframe, TimestampTimeframe, JoinRelationship, type Field, type SerializedExplore, type SortableField, type PreparedResultJSON, type BuildPlan, Explore, ExploreField, AtomicField, DateField, TimestampField, NumberField, BooleanField, JSONField, UnsupportedField, StringField, Query, QueryField, Model, PersistSource, PreparedQuery, PreparedResult, } from './core';
+export { SourceRelationship, AtomicFieldType, DateTimeframe, TimestampTimeframe, JoinRelationship, type Field, type SerializedExplore, type SortableField, type PreparedResultJSON, type BuildPlan, Explore, ExploreField, AtomicField, DateField, TimestampField, NumberField, BooleanField, JSONField, UnsupportedField, StringField, Query, QueryField, Model, PersistSource, PreparedQuery, PreparedResult, Reference, type ReferenceKind, } from './core';
 export { type ResultJSON, type DataColumn, type DataArrayOrRecord, Result, DataArray, DataRecord, } from './result';
 export { type WriteStream, DataWriter, JSONWriter, CSVWriter } from './writers';
 export { Runtime, ConnectionRuntime, SingleConnectionRuntime, ModelMaterializer, QueryMaterializer, PreparedResultMaterializer, ExploreMaterializer, } from './runtime';

package/dist/api/foundation/index.js

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: MIT
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExploreMaterializer = exports.PreparedResultMaterializer = exports.QueryMaterializer = exports.ModelMaterializer = exports.SingleConnectionRuntime = exports.ConnectionRuntime = exports.Runtime = exports.CSVWriter = exports.JSONWriter = exports.DataWriter = exports.DataRecord = exports.DataArray = exports.Result = exports.PreparedResult = exports.PreparedQuery = exports.PersistSource = exports.Model = exports.QueryField = exports.Query = exports.StringField = exports.UnsupportedField = exports.JSONField = exports.BooleanField = exports.NumberField = exports.TimestampField = exports.DateField = exports.AtomicField = exports.ExploreField = exports.Explore = exports.JoinRelationship = exports.TimestampTimeframe = exports.DateTimeframe = exports.AtomicFieldType = exports.SourceRelationship = exports.DocumentCompletion = exports.DocumentSymbol = exports.DocumentPosition = exports.DocumentRange = exports.DocumentTablePath = exports.Parse = exports.InMemoryModelCache = exports.CacheManager = exports.getInvalidationKey = exports.readURL = exports.isInternalURL = exports.hashForInvalidationKey = exports.FixedConnectionMap = exports.InMemoryURLReader = exports.EmptyURLReader = exports.EMPTY_BUILD_MANIFEST = void 0;
-exports.MalloyError = exports.Malloy = exports.discoverConfig = exports.defaultConfigOverlays = exports.contextOverlay = exports.envOverlay = exports.MalloyConfig = exports.Manifest = void 0;
+exports.PreparedResultMaterializer = exports.QueryMaterializer = exports.ModelMaterializer = exports.SingleConnectionRuntime = exports.ConnectionRuntime = exports.Runtime = exports.CSVWriter = exports.JSONWriter = exports.DataWriter = exports.DataRecord = exports.DataArray = exports.Result = exports.Reference = exports.PreparedResult = exports.PreparedQuery = exports.PersistSource = exports.Model = exports.QueryField = exports.Query = exports.StringField = exports.UnsupportedField = exports.JSONField = exports.BooleanField = exports.NumberField = exports.TimestampField = exports.DateField = exports.AtomicField = exports.ExploreField = exports.Explore = exports.JoinRelationship = exports.TimestampTimeframe = exports.DateTimeframe = exports.AtomicFieldType = exports.SourceRelationship = exports.DocumentCompletion = exports.DocumentSymbol = exports.DocumentPosition = exports.DocumentRange = exports.DocumentTablePath = exports.Parse = exports.InMemoryModelCache = exports.CacheManager = exports.getInvalidationKey = exports.readURL = exports.isInternalURL = exports.hashForInvalidationKey = exports.FixedConnectionMap = exports.InMemoryURLReader = exports.EmptyURLReader = exports.EMPTY_BUILD_MANIFEST = void 0;
+exports.MalloyError = exports.Malloy = exports.discoverConfig = exports.defaultConfigOverlays = exports.contextOverlay = exports.envOverlay = exports.MalloyConfig = exports.Manifest = exports.ExploreMaterializer = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "EMPTY_BUILD_MANIFEST", { enumerable: true, get: function () { return types_1.EMPTY_BUILD_MANIFEST; } });
 // URL readers and connection helpers
@@ -53,6 +53,7 @@ Object.defineProperty(exports, "Model", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "PersistSource", { enumerable: true, get: function () { return core_1.PersistSource; } });
 Object.defineProperty(exports, "PreparedQuery", { enumerable: true, get: function () { return core_1.PreparedQuery; } });
 Object.defineProperty(exports, "PreparedResult", { enumerable: true, get: function () { return core_1.PreparedResult; } });
+Object.defineProperty(exports, "Reference", { enumerable: true, get: function () { return core_1.Reference; } });
 // Result and Data classes
 var result_1 = require("./result");
 Object.defineProperty(exports, "Result", { enumerable: true, get: function () { return result_1.Result; } });

package/dist/api/foundation/runtime.js

@@ -873,8 +873,8 @@ exports.ModelMaterializer = ModelMaterializer;
 // =============================================================================
 function runSQLOptionsWithAnnotations(preparedResult, givenOptions) {
     return {
-        queryAnnotation: preparedResult.annotation,
-        modelAnnotation: preparedResult.modelAnnotation,
+        queryAnnotations: preparedResult._rawQuery.annotations,
+        modelAnnotations: preparedResult._modelDef.annotations,
         ...givenOptions,
     };
 }

package/dist/{taggable.d.ts → api/foundation/taggable.d.ts}

@@ -8,17 +8,17 @@ export interface Taggable {
     /**
      * Route-aware annotation access — read annotations by *route*. See
      * `Annotations` for what a route is and which ones are claimed. Unlike
-     * `tagParse`/`getTaglines`, this sees block annotations (`#|`…`|#`).
+     * `tagParse`/`getTaglines`, this sees multi-line annotations (`#|`…`|#`).
      */
     readonly annotations: Annotations;
     /**
-     * @deprecated The RegExp form cannot see block annotations (`#|`…`|#`) and
-     * cannot report content offsets for error mapping. Use
+     * @deprecated The RegExp form cannot see multi-line annotations
+     * (`#|`…`|#`) and cannot report content offsets for error mapping. Use
      * `annotations.parseAsTag(route)` instead.
      */
     tagParse: (spec?: TagParseSpec) => MalloyTagParse;
     /**
-     * @deprecated The RegExp form cannot see block annotations. Use
+     * @deprecated The RegExp form cannot see multi-line annotations. Use
      * `annotations.texts(route)` (raw strings) or `annotations.forRoute(route)`
      * (objects with offsets) instead.
      */

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

@@ -9,7 +9,7 @@ import type { BuildManifest, GivenValue, VirtualMap } from '../../model';
  * Frozen to prevent accidental mutation of the shared sentinel.
  */
 export declare const EMPTY_BUILD_MANIFEST: BuildManifest;
-export type { Taggable } from '../../taggable';
+export type { Taggable } from './taggable';
 export interface Loggable {
     debug: (message?: any, ...optionalParams: any[]) => void;
     info: (message?: any, ...optionalParams: any[]) => void;

package/dist/connection/types.d.ts

@@ -1,12 +1,13 @@
 import type { RunSQLOptions } from '../run_sql_options';
-import type { Annotation, MalloyQueryData, QueryRecord, QueryRunStats, SQLSourceDef, TableSourceDef } from '../model/malloy_types';
+import type { AnnotationsDef, MalloyQueryData, QueryRecord, QueryRunStats, SQLSourceDef, TableSourceDef } from '../model/malloy_types';
 import type { SQLSourceRequest } from '../lang/translate-response';
 /**
  * Options passed to fetchSchema methods.
  */
 export interface FetchSchemaOptions {
     refreshTimestamp?: number;
-    modelAnnotation?: Annotation;
+    /** Model annotations forwarded to the adapter (e.g. `##!` dialect flags). */
+    modelAnnotations?: AnnotationsDef;
 }
 /**
  * An object capable of reading schemas for given table names.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { DuckDBDialect, StandardSQLDialect, TrinoDialect, PostgresDialect, SnowflakeDialect, MySQLDialect, DatabricksDialect, registerDialect, arg, qtz, overload, minScalar, anyExprType, minAggregate, maxScalar, sql, makeParam, param, variadicParam, literal, spread, Dialect, decodeDottedTablePath, validateDottedTablePath, } from './dialect';
 export type { DialectFieldList, DialectFunctionOverloadDef, QueryInfo, MalloyStandardFunctionImplementations, DefinitionBlueprint, DefinitionBlueprintMap, OverloadedDefinitionBlueprint, DecodeDottedTablePathResult, DottedTablePathOptions, TablePathEscapeStyle, TablePathSegment, ValidateTablePathResult, } from './dialect';
-export type { QueryRecord, StructDef, TableSourceDef, SQLSourceDef, SourceDef, JoinFieldDef, NamedSourceDefs, MalloyQueryData, DateUnit, ExtractUnit, TimestampUnit, TemporalFieldType, QueryData, QueryValue, Expr, FilterCondition, Argument, Parameter, FieldDef, PipeSegment, QueryFieldDef, IndexFieldDef, TurtleDef, SearchValueMapResult, SearchIndexResult, ModelDef, Query, QueryResult, QueryResultDef, QueryRunStats, QueryScalar, NamedQueryDef, NamedModelObject, ExpressionType, FunctionDef, FunctionOverloadDef, FunctionParameterDef, ExpressionValueType, TypeDesc, FunctionParamTypeDesc, DocumentLocation, DocumentRange, DocumentPosition, Sampling, Annotation, BasicAtomicTypeDef, BasicAtomicDef, AtomicTypeDef, AtomicFieldDef, ArrayDef, ArrayTypeDef, RecordTypeDef, RepeatedRecordTypeDef, RecordDef, RepeatedRecordDef, RecordLiteralNode, StringLiteralNode, ArrayLiteralNode, SourceComponentInfo, DateLiteralNode, TimestampLiteralNode, TimestamptzLiteralNode, TimeLiteralExpr, TypecastExpr, BuildID, BuildManifest, BuildManifestEntry, GivenValue, VirtualMap, } from './model';
+export type { QueryRecord, StructDef, TableSourceDef, SQLSourceDef, SourceDef, JoinFieldDef, NamedSourceDefs, MalloyQueryData, DateUnit, ExtractUnit, TimestampUnit, TemporalFieldType, QueryData, QueryValue, Expr, FilterCondition, Argument, Parameter, FieldDef, PipeSegment, QueryFieldDef, IndexFieldDef, TurtleDef, SearchValueMapResult, SearchIndexResult, ModelDef, Query, QueryResult, QueryResultDef, QueryRunStats, QueryScalar, NamedQueryDef, NamedModelObject, ExpressionType, FunctionDef, FunctionOverloadDef, FunctionParameterDef, ExpressionValueType, TypeDesc, FunctionParamTypeDesc, DocumentLocation, DocumentRange, DocumentPosition, Sampling, BasicAtomicTypeDef, BasicAtomicDef, AtomicTypeDef, AtomicFieldDef, ArrayDef, ArrayTypeDef, RecordTypeDef, RepeatedRecordTypeDef, RecordDef, RepeatedRecordDef, RecordLiteralNode, StringLiteralNode, ArrayLiteralNode, SourceComponentInfo, DateLiteralNode, TimestampLiteralNode, TimestamptzLiteralNode, TimeLiteralExpr, TypecastExpr, BuildID, BuildManifest, BuildManifestEntry, GivenValue, VirtualMap, } from './model';
 export { isSourceDef, isAtomic, isBasicAtomic, isCompoundArrayData, isJoined, isJoinedSource, isSamplingEnable, isSamplingPercent, isSamplingRows, isRepeatedRecord, isBasicArray, mkArrayDef, mkFieldDef, expressionIsAggregate, expressionIsAnalytic, expressionIsCalculation, expressionIsScalar, expressionIsUngroupedAggregate, indent, composeSQLExpr, isTimestampUnit, isDateUnit, constantExprToSQL, } from './model';
 export { malloyToQuery, MalloyTranslator, } from './lang';
 export type { LogMessage, TranslateResponse } from './lang';
@@ -19,7 +19,14 @@ export { modelDefToModelInfo, sourceDefToSourceInfo } from './to_stable';
 export * as API from './api';
 export type { SQLSourceRequest } from './lang/translate-response';
 export { sqlKey } from './model/sql_block';
-export { annotationToTag, annotationToTaglines } from './annotation';
+export { Annotations, RoutedNote } from './api/foundation/annotation';
+export { routeOf, payloadOf, annotationsForRoute, tagFromAnnotations, } from './api/annotation-utils';
+/** @deprecated — use the `.annotations` view on a Foundation entity
+ *  (`entity.annotations.parseAsTag(route)` / `.texts(route)`). */
+export { annotationToTag, annotationToTaglines, } from './api/foundation/annotation';
 export type { BuildGraph, BuildNode, BuildPlan } from './api/foundation';
 export { PersistSource, EMPTY_BUILD_MANIFEST } from './api/foundation';
+export { Reference } from './api/foundation';
+export type { ReferenceKind } from './api/foundation';
+export type { ImportLocation } from './model';
 export { makeDigest } from './model';

package/dist/index.js

@@ -34,7 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Model = exports.MalloyTranslator = exports.malloyToQuery = exports.constantExprToSQL = exports.isDateUnit = exports.isTimestampUnit = exports.composeSQLExpr = exports.indent = exports.expressionIsUngroupedAggregate = exports.expressionIsScalar = exports.expressionIsCalculation = exports.expressionIsAnalytic = exports.expressionIsAggregate = exports.mkFieldDef = exports.mkArrayDef = exports.isBasicArray = exports.isRepeatedRecord = exports.isSamplingRows = exports.isSamplingPercent = exports.isSamplingEnable = exports.isJoinedSource = exports.isJoined = exports.isCompoundArrayData = exports.isBasicAtomic = exports.isAtomic = exports.isSourceDef = exports.validateDottedTablePath = exports.decodeDottedTablePath = exports.Dialect = exports.spread = exports.literal = exports.variadicParam = exports.param = exports.makeParam = exports.sql = exports.maxScalar = exports.minAggregate = exports.anyExprType = exports.minScalar = exports.overload = exports.qtz = exports.arg = exports.registerDialect = exports.DatabricksDialect = exports.MySQLDialect = exports.SnowflakeDialect = exports.PostgresDialect = exports.TrinoDialect = exports.StandardSQLDialect = exports.DuckDBDialect = void 0;
-exports.makeDigest = exports.EMPTY_BUILD_MANIFEST = exports.PersistSource = exports.annotationToTaglines = exports.annotationToTag = exports.sqlKey = exports.API = exports.sourceDefToSourceInfo = exports.modelDefToModelInfo = exports.toAsyncGenerator = exports.createConnectionsFromConfig = exports.getRegisteredConnectionTypes = exports.getConnectionTypeDisplayName = exports.getConnectionProperties = exports.registerConnectionType = exports.discoverConfig = exports.defaultConfigOverlays = exports.contextOverlay = exports.envOverlay = exports.MalloyConfig = exports.Manifest = exports.CacheManager = exports.InMemoryModelCache = exports.Explore = exports.DataWriter = exports.Parse = exports.JSONWriter = exports.CSVWriter = exports.QueryMaterializer = exports.Result = exports.PreparedResult = exports.TimestampTimeframe = exports.DateTimeframe = exports.SourceRelationship = exports.JoinRelationship = exports.MalloyError = exports.FixedConnectionMap = exports.InMemoryURLReader = exports.EmptyURLReader = exports.SingleConnectionRuntime = exports.ConnectionRuntime = exports.AtomicFieldType = exports.Runtime = exports.Malloy = void 0;
+exports.Reference = exports.EMPTY_BUILD_MANIFEST = exports.PersistSource = exports.annotationToTaglines = exports.annotationToTag = exports.tagFromAnnotations = exports.annotationsForRoute = exports.payloadOf = exports.routeOf = exports.RoutedNote = exports.Annotations = exports.sqlKey = exports.API = exports.sourceDefToSourceInfo = exports.modelDefToModelInfo = exports.toAsyncGenerator = exports.createConnectionsFromConfig = exports.getRegisteredConnectionTypes = exports.getConnectionTypeDisplayName = exports.getConnectionProperties = exports.registerConnectionType = exports.discoverConfig = exports.defaultConfigOverlays = exports.contextOverlay = exports.envOverlay = exports.MalloyConfig = exports.Manifest = exports.CacheManager = exports.InMemoryModelCache = exports.Explore = exports.DataWriter = exports.Parse = exports.JSONWriter = exports.CSVWriter = exports.QueryMaterializer = exports.Result = exports.PreparedResult = exports.TimestampTimeframe = exports.DateTimeframe = exports.SourceRelationship = exports.JoinRelationship = exports.MalloyError = exports.FixedConnectionMap = exports.InMemoryURLReader = exports.EmptyURLReader = exports.SingleConnectionRuntime = exports.ConnectionRuntime = exports.AtomicFieldType = exports.Runtime = exports.Malloy = void 0;
+exports.makeDigest = void 0;
 /*
  * Copyright 2023 Google LLC
  *
@@ -157,12 +158,24 @@ Object.defineProperty(exports, "sourceDefToSourceInfo", { enumerable: true, get:
 exports.API = __importStar(require("./api"));
 var sql_block_1 = require("./model/sql_block");
 Object.defineProperty(exports, "sqlKey", { enumerable: true, get: function () { return sql_block_1.sqlKey; } });
-var annotation_1 = require("./annotation");
-Object.defineProperty(exports, "annotationToTag", { enumerable: true, get: function () { return annotation_1.annotationToTag; } });
-Object.defineProperty(exports, "annotationToTaglines", { enumerable: true, get: function () { return annotation_1.annotationToTaglines; } });
+var annotation_1 = require("./api/foundation/annotation");
+Object.defineProperty(exports, "Annotations", { enumerable: true, get: function () { return annotation_1.Annotations; } });
+Object.defineProperty(exports, "RoutedNote", { enumerable: true, get: function () { return annotation_1.RoutedNote; } });
+var annotation_utils_1 = require("./api/annotation-utils");
+Object.defineProperty(exports, "routeOf", { enumerable: true, get: function () { return annotation_utils_1.routeOf; } });
+Object.defineProperty(exports, "payloadOf", { enumerable: true, get: function () { return annotation_utils_1.payloadOf; } });
+Object.defineProperty(exports, "annotationsForRoute", { enumerable: true, get: function () { return annotation_utils_1.annotationsForRoute; } });
+Object.defineProperty(exports, "tagFromAnnotations", { enumerable: true, get: function () { return annotation_utils_1.tagFromAnnotations; } });
+/** @deprecated — use the `.annotations` view on a Foundation entity
+ *  (`entity.annotations.parseAsTag(route)` / `.texts(route)`). */
+var annotation_2 = require("./api/foundation/annotation");
+Object.defineProperty(exports, "annotationToTag", { enumerable: true, get: function () { return annotation_2.annotationToTag; } });
+Object.defineProperty(exports, "annotationToTaglines", { enumerable: true, get: function () { return annotation_2.annotationToTaglines; } });
 var foundation_2 = require("./api/foundation");
 Object.defineProperty(exports, "PersistSource", { enumerable: true, get: function () { return foundation_2.PersistSource; } });
 Object.defineProperty(exports, "EMPTY_BUILD_MANIFEST", { enumerable: true, get: function () { return foundation_2.EMPTY_BUILD_MANIFEST; } });
+var foundation_3 = require("./api/foundation");
+Object.defineProperty(exports, "Reference", { enumerable: true, get: function () { return foundation_3.Reference; } });
 var model_2 = require("./model");
 Object.defineProperty(exports, "makeDigest", { enumerable: true, get: function () { return model_2.makeDigest; } });
 //# sourceMappingURL=index.js.map

package/dist/{prefix.js → lang/annotation-prefix.js}

@@ -96,4 +96,4 @@ function parsePrefix(text) {
     // Otherwise: a bare word, or mixed text with no brackets.
     return { route: routing, contentIndex, malformation: 'malformed-route' };
 }
-//# sourceMappingURL=prefix.js.map
+//# sourceMappingURL=annotation-prefix.js.map

package/dist/lang/ast/expressions/expr-given.js

@@ -46,7 +46,7 @@ class GivenReference extends expression_def_1.ExpressionDef {
             location: this.location,
             definition: {
                 type: (0, utils_1.typeDefToString)(given.type),
-                annotation: given.annotation,
+                annotations: given.annotations,
                 location: given.location,
                 defaultText: given.defaultText,
             },

package/dist/lang/ast/field-space/dynamic-space.d.ts

@@ -13,7 +13,7 @@ export declare abstract class DynamicSpace extends StaticSpace implements Source
     private parameters;
     protected newTimezone?: string;
     protected newAccessModifiers: Map<string, model.AccessModifierLabel>;
-    protected newNotes: Map<string, model.Annotation>;
+    protected newNotes: Map<string, model.AnnotationsDef>;
     constructor(extending: SourceDef);
     protected setEntry(name: string, value: SpaceEntry): void;
     addParameters(parameters: HasParameter[]): DynamicSpace;

package/dist/lang/ast/field-space/dynamic-space.js

@@ -191,9 +191,9 @@ class DynamicSpace extends static_space_1.StaticSpace {
                 const field = this.sourceDef.fields[index];
                 this.sourceDef.fields[index] = {
                     ...field,
-                    annotation: {
+                    annotations: {
                         ...note,
-                        inherits: field.annotation,
+                        inherits: field.annotations,
                     },
                 };
             }

package/dist/lang/ast/field-space/include-utils.d.ts

@@ -1,9 +1,9 @@
-import type { AccessModifierLabel, Annotation, DocumentLocation, SourceDef } from '../../../model/malloy_types';
+import type { AccessModifierLabel, AnnotationsDef, DocumentLocation, SourceDef } from '../../../model/malloy_types';
 import type { IncludeItem } from '../source-query-elements/include-item';
 import type { FieldReference } from '../query-items/field-references';
 export interface JoinIncludeProcessingState {
     star: AccessModifierLabel | 'inherit' | 'except' | undefined;
-    starNote: Annotation | undefined;
+    starNote: AnnotationsDef | undefined;
     fieldsIncluded: Set<string>;
     joinNames: Set<string>;
     fieldsExcepted: Set<string>;
@@ -16,7 +16,7 @@ export interface JoinIncludeProcessingState {
         location: DocumentLocation;
     }[];
     fieldsToInclude: Set<string> | undefined;
-    notes: Map<string, Annotation>;
+    notes: Map<string, AnnotationsDef>;
 }
 export interface IncludeProcessingState {
     joins: {

package/dist/lang/ast/field-space/query-spaces.js

@@ -309,8 +309,8 @@ class QuerySpace extends QueryOperationSpace {
             throw new Error('Invalid type for fieldref');
         }
         ret.location = (_c = ret.location) !== null && _c !== void 0 ? _c : this.astEl.location;
-        if (queryFieldDef.annotation) {
-            ret.annotation = queryFieldDef.annotation;
+        if (queryFieldDef.annotations) {
+            ret.annotations = queryFieldDef.annotations;
         }
         return ret;
     }

package/dist/lang/ast/field-space/reference-field.js

@@ -113,12 +113,12 @@ class ReferenceField extends space_field_1.SpaceField {
                 const origFd = refTo.constructorFieldDef();
                 if (origFd) {
                     const notes = this.fieldRef.note;
-                    if (origFd.annotation || notes) {
-                        const annotation = notes || {};
-                        if (origFd.annotation) {
-                            annotation.inherits = origFd.annotation;
+                    if (origFd.annotations || notes) {
+                        const annotations = notes || {};
+                        if (origFd.annotations) {
+                            annotations.inherits = origFd.annotations;
                         }
-                        this.queryFieldDef.annotation = annotation;
+                        this.queryFieldDef.annotations = annotations;
                     }
                 }
             }

package/dist/lang/ast/field-space/refined-space.d.ts

@@ -1,4 +1,4 @@
-import { type AccessModifierLabel, type Annotation, type SourceDef } from '../../../model/malloy_types';
+import { type AccessModifierLabel, type AnnotationsDef, type SourceDef } from '../../../model/malloy_types';
 import type { FieldListEdit } from '../source-properties/field-list-edit';
 import { DynamicSpace } from './dynamic-space';
 import type { MalloyElement } from '../types/malloy-element';
@@ -14,6 +14,6 @@ export declare class RefinedSpace extends DynamicSpace {
     pushFields(...defs: MalloyElement[]): void;
     addField(def: MalloyElement): void;
     addAccessModifiers(ams: Map<string, AccessModifierLabel>): void;
-    addNotes(notes: Map<string, Annotation>): void;
+    addNotes(notes: Map<string, AnnotationsDef>): void;
     accessProtectionLevel(): AccessModifierLabel;
 }

package/dist/lang/ast/field-space/refined-space.js

@@ -160,13 +160,13 @@ function editJoinsFromIncludeState(path, from, includeState) {
                 ...field,
                 as: rename ? rename.name.nameString : field.as,
                 accessModifier: accessModifier === 'public' ? undefined : accessModifier,
-                annotation: notes
+                annotations: notes
                     ? {
-                        inherits: field.annotation,
+                        inherits: field.annotations,
                         blockNotes: notes.blockNotes,
                         notes: notes.notes,
                     }
-                    : field.annotation,
+                    : field.annotations,
             }
             : { ...field };
         if ((0, malloy_types_1.isJoined)(editedField)) {