@malloydata/malloy 0.0.395 → 0.0.397

package/dist/annotation.d.ts

@@ -1,12 +1,96 @@
 import type { Tag } from '@malloydata/malloy-tag';
-import type { Annotation } from './model';
+import type { Annotation, DocumentLocation } from './model';
 import type { LogMessage } from './lang';
+/**
+ * @deprecated Argument shape for the deprecated RegExp form of
+ * {@link annotationToTag}. The RegExp form cannot see block 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, unparsed — its raw text and where its content begins. */
+export interface AnnotationText {
+    /** The annotation exactly as written — prefix + content. */
+    rawText: string;
+    /** Offset where the content begins; `rawText.slice(contentIndex)` is the content. */
+    contentIndex: number;
+    /** Where `rawText` begins in the source document. */
+    at: DocumentLocation;
+    /**
+     * For block annotations: characters of leading whitespace removed from
+     * each body line by the translator's dedent pass. A BYO parser that wants
+     * source-mapped error columns adds this to the parser's reported column for
+     * body lines (`source_col = indentStripped + parser_col`).
+     */
+    indentStripped?: number;
+}
+/** An {@link AnnotationText} that also carries its route (`''` is MOTLY). */
+export interface RoutedAnnotation extends AnnotationText {
+    route: 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, `route` omitted from each result
+ *   (you passed it); malformed prefixes excluded.
+ */
+export declare function collectAnnotations(annote: Annotation | undefined): RoutedAnnotation[];
+export declare function collectAnnotations(annote: Annotation | undefined, route: string): AnnotationText[];
+/**
+ * @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)`).
+ */
 export declare function annotationToTaglines(annote: Annotation | 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: Annotation | undefined, route?: string): MalloyTagParse;
+/**
+ * @deprecated The RegExp `prefix` form cannot see block 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: Annotation | 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 `./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.
+ */
+export declare class Annotations {
+    private readonly annote;
+    constructor(annote: Annotation | 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 (bring-your-own
+     * parsers), see {@link forRoute}.
+     */
+    texts(route?: string): string[];
+    /**
+     * 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.
+     */
+    forRoute(route: string): AnnotationText[];
+    /** Parse a route's annotations as a MOTLY tag. Default `''` is the tag route. */
+    parseAsTag(route?: string): MalloyTagParse;
+}

package/dist/annotation.js

@@ -1,50 +1,80 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Annotations = void 0;
+exports.collectAnnotations = collectAnnotations;
 exports.annotationToTaglines = annotationToTaglines;
 exports.annotationToTag = annotationToTag;
 const malloy_tag_1 = require("@malloydata/malloy-tag");
+const prefix_1 = require("./prefix");
+/** Every Note of an annotation, inherited first, in document order. */
+function* notesInOrder(annote) {
+    if (annote.inherits)
+        yield* notesInOrder(annote.inherits);
+    if (annote.blockNotes)
+        yield* annote.blockNotes;
+    if (annote.notes)
+        yield* annote.notes;
+}
+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,
+            });
+        }
+    }
+    return matching;
+}
 /**
  * Collect all matching Notes from an Annotation, walking the inherits
  * chain. Returns notes in inheritance order (inherited first).
+ *
+ * @deprecated RegExp prefix matching; use {@link collectAnnotations} with a route.
  */
 function collectNotes(annote, prefix) {
-    const inherited = annote.inherits
-        ? collectNotes(annote.inherits, prefix)
-        : [];
-    const allNotes = [];
-    if (annote.blockNotes) {
-        allNotes.push(...annote.blockNotes);
-    }
-    if (annote.notes) {
-        allNotes.push(...annote.notes);
-    }
-    if (prefix) {
-        const matching = allNotes.filter(note => note.text.match(prefix));
-        return inherited.concat(matching);
-    }
-    return inherited.concat(allNotes);
+    const notes = [...notesInOrder(annote)];
+    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)`).
+ */
 function annotationToTaglines(annote, prefix) {
     return collectNotes(annote || {}, prefix).map(n => n.text);
 }
-function annotationToTag(annote, spec = {}) {
-    const prefix = spec.prefix || /^##? /;
-    annote || (annote = {});
-    const notes = collectNotes(annote, prefix);
+/** Parse a run of Notes as MOTLY into one Tag, collecting errors. */
+function parseTaglines(lines) {
     const allErrs = [];
     const session = new malloy_tag_1.TagParser();
-    for (const note of notes) {
+    for (const line of lines) {
         const origin = {
-            url: note.at.url,
-            startLine: note.at.range.start.line,
-            startColumn: note.at.range.start.character,
+            url: line.at.url,
+            startLine: line.at.range.start.line,
+            startColumn: line.at.range.start.character,
         };
-        const noteParse = session.parseAnnotation(note.text, origin);
-        allErrs.push(...noteParse.log.map((e) => mapMalloyError(e, note)));
+        const noteParse = session.parseAnnotation(line.text, origin);
+        allErrs.push(...noteParse.log.map((e) => mapMalloyError(e, line)));
     }
     const tag = session.finish();
-    const refErrors = tag.validateReferences();
-    for (const refError of refErrors) {
+    for (const refError of tag.validateReferences()) {
         allErrs.push({
             code: 'tag-reference-error',
             severity: 'warn',
@@ -53,25 +83,78 @@ function annotationToTag(annote, spec = {}) {
     }
     return { tag, log: allErrs };
 }
-function mapMalloyError(e, note) {
-    // Calculate prefix length (same logic as stripPrefix in malloy-tag)
-    let prefixLen = 0;
-    if (note.text[0] === '#') {
-        const skipTo = note.text.search(/[ \n]/);
-        if (skipTo > 0) {
-            prefixLen = skipTo;
-        }
+function annotationToTag(annote, arg) {
+    if (typeof arg === 'object') {
+        const prefix = arg.prefix || /^##? /;
+        return parseTaglines(collectNotes(annote !== null && annote !== void 0 ? annote : {}, prefix));
+    }
+    const matched = collectAnnotations(annote, arg !== null && arg !== void 0 ? arg : '');
+    return parseTaglines(matched.map(a => ({
+        text: a.rawText,
+        at: a.at,
+        indentStripped: a.indentStripped,
+    })));
+}
+/**
+ * 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 `./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.
+ */
+class Annotations {
+    constructor(annote) {
+        this.annote = annote;
     }
-    // Map error position to source location
-    // e.line is 0-based line within the (stripped) input
-    // e.offset is 0-based column within that line
-    // TODO: For block annotations, lines > 0 have indentation stripped by
-    // stripBlockIndent, so e.offset doesn't account for the removed columns.
-    // This makes error squigglies misaligned on block annotation body lines.
+    /**
+     * 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}.
+     */
+    texts(route) {
+        const items = route === undefined
+            ? collectAnnotations(this.annote)
+            : collectAnnotations(this.annote, route);
+        return items.map(a => a.rawText);
+    }
+    /**
+     * 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.
+     */
+    forRoute(route) {
+        return collectAnnotations(this.annote, route);
+    }
+    /** Parse a route's annotations as a MOTLY tag. Default `''` is the tag route. */
+    parseAsTag(route = '') {
+        return annotationToTag(this.annote, route);
+    }
+}
+exports.Annotations = Annotations;
+function mapMalloyError(e, note) {
+    var _a;
+    // MOTLY reports `e.line` / `e.offset` into the *stripped* note text it
+    // parsed. To map back to source:
+    //   line 0 (opener line):    col = opener_col + prefix_len + e.offset
+    //   line N>0 (body lines):   col = indentStripped + e.offset
+    // `indentStripped` is the per-line dedent recorded on the Note by the
+    // translator (uniform per block, so the same formula serves every body
+    // line). Prefix length is everything before the separator, via parsePrefix.
     const line = note.at.range.start.line + e.line;
     const character = e.line === 0
-        ? note.at.range.start.character + prefixLen + e.offset
-        : e.offset;
+        ? note.at.range.start.character + prefixLength(note.text) + e.offset
+        : ((_a = note.indentStripped) !== null && _a !== void 0 ? _a : 0) + e.offset;
     const loc = { line, character };
     return {
         code: 'tag-parse-error',
@@ -79,11 +162,14 @@ function mapMalloyError(e, note) {
         message: e.message,
         at: {
             url: note.at.url,
-            range: {
-                start: loc,
-                end: loc,
-            },
+            range: { start: loc, end: loc },
         },
     };
 }
+/** 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);
+    return contentIndex === text.length ? 0 : contentIndex - 1;
+}
 //# sourceMappingURL=annotation.js.map

package/dist/api/core.js

@@ -56,7 +56,6 @@ const lang_1 = require("../lang");
 const model_1 = require("../model");
 const to_stable_1 = require("../to_stable");
 const sql_block_1 = require("../model/sql_block");
-const annotation_1 = require("../annotation");
 const malloy_tag_1 = require("@malloydata/malloy-tag");
 const util_1 = require("./util");
 const timing_1 = require("../timing");
@@ -506,9 +505,7 @@ function statedCompileQuery(state) {
                 defaultRowLimit: state.defaultRowLimit,
             });
             timer.contribute([sqlTimer.stop()]);
-            const modelAnnotations = (0, annotation_1.annotationToTaglines)(result.modelDef.annotation).map(l => ({
-                value: l,
-            }));
+            const modelAnnotations = (0, to_stable_1.toStableAnnotations)(result.modelDef.annotation);
             let source;
             if (query.compositeResolvedSourceDef) {
                 source = query.compositeResolvedSourceDef;
@@ -522,9 +519,7 @@ function statedCompileQuery(state) {
                     source = (0, model_1.safeRecordGet)(result.modelDef.contents, query.structRef);
                 }
             }
-            const sourceAnnotations = (0, annotation_1.annotationToTaglines)(source.annotation).map(l => ({
-                value: l,
-            }));
+            const sourceAnnotations = (0, to_stable_1.toStableAnnotations)(source.annotation);
             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/compile.d.ts

@@ -54,6 +54,12 @@ export declare class MalloyError extends Error {
      */
     constructor(message: string, problems?: LogMessage[]);
 }
+type CompileRequest = Compilable & CompileOptions & CompileQueryOptions & ParseOptions & {
+    urlReader: URLReader;
+    connections: LookupConnection<InfoConnection>;
+    model?: Model;
+    cacheManager?: CacheManager;
+};
 export declare class Malloy {
     static get version(): string;
     /**
@@ -109,12 +115,7 @@ export declare class Malloy {
      * @param model A compiled model to build upon (optional).
      * @return A (promise of a) compiled `Model`.
      */
-    static compile({ url, source, parse, urlReader, connections, model, refreshSchemaCache, noThrowOnError, eventStream, importBaseURL, cacheManager, }: {
-        urlReader: URLReader;
-        connections: LookupConnection<InfoConnection>;
-        model?: Model;
-        cacheManager?: CacheManager;
-    } & Compilable & CompileOptions & CompileQueryOptions & ParseOptions): Promise<Model>;
+    static compile(req: CompileRequest): Promise<Model>;
     /**
      * A dialect must provide a response for every table, or the translator loop
      * will never exit. Because there was a time when this happened, we throw

package/dist/api/foundation/compile.js

@@ -37,9 +37,6 @@ class MalloyError extends Error {
     }
 }
 exports.MalloyError = MalloyError;
-// =============================================================================
-// Malloy Static Class
-// =============================================================================
 class Malloy {
     static get version() {
         return version_1.MALLOY_VERSION;
@@ -70,6 +67,7 @@ class Malloy {
         return (0, registry_1.getRegisteredConnectionTypes)();
     }
     static _parse(source, url, eventStream, options, invalidationKey) {
+        var _a;
         if (url === undefined) {
             url = new URL(MALLOY_INTERNAL_URL);
         }
@@ -79,7 +77,7 @@ class Malloy {
         }
         const translator = new lang_1.MalloyTranslator(url.toString(), importBaseURL.toString(), {
             urls: { [url.toString()]: source },
-        }, eventStream);
+        }, eventStream, (_a = options === null || options === void 0 ? void 0 : options.restrictedMode) !== null && _a !== void 0 ? _a : false);
         if (options === null || options === void 0 ? void 0 : options.testEnvironment) {
             translator.allDialectsEnabled = true;
         }
@@ -110,8 +108,19 @@ class Malloy {
      * @param model A compiled model to build upon (optional).
      * @return A (promise of a) compiled `Model`.
      */
-    static async compile({ url, source, parse, urlReader, connections, model, refreshSchemaCache, noThrowOnError, eventStream, importBaseURL, cacheManager, }) {
+    static async compile(req) {
         var _a, _b, _c, _d, _e;
+        let { url, source, importBaseURL, cacheManager } = req;
+        const { parse, urlReader, connections, model, refreshSchemaCache, noThrowOnError, eventStream, restrictedMode, } = req;
+        if (restrictedMode) {
+            // Restricted-mode compiles do not participate in the model-def
+            // cache. The cache key is the URL, but restricted vs. unrestricted
+            // produces different validation outcomes, so allowing a restricted
+            // compile to serve from (or write to) the same cache as
+            // unrestricted compiles would let restricted mode be bypassed by a
+            // prior unrestricted compile of the same URL.
+            cacheManager = undefined;
+        }
         let refreshTimestamp;
         if (refreshSchemaCache) {
             refreshTimestamp =
@@ -145,6 +154,13 @@ class Malloy {
         // It's not cached, so we may need to get the actual source
         const _url = url.toString();
         if (parse !== undefined) {
+            // A pre-parsed translator's restrictedMode was fixed at parse
+            // time and cannot be changed here. Loudly reject mismatched
+            // requests rather than silently inheriting the parse-time value.
+            if (restrictedMode !== undefined &&
+                parse._translator.restrictedMode !== restrictedMode) {
+                throw new Error(`Malloy.compile: restrictedMode (${restrictedMode}) does not match the pre-parsed translator's restrictedMode (${parse._translator.restrictedMode}). Set restrictedMode at parse time.`);
+            }
             translator = parse._translator;
             const invalidationKey = (_a = parse._invalidationKey) !== null && _a !== void 0 ? _a : (await (0, readers_1.getInvalidationKey)(urlReader, url));
             invalidationKeys[_url] = invalidationKey;
@@ -161,7 +177,7 @@ class Malloy {
             }
             translator = new lang_1.MalloyTranslator(_url, importBaseURL.toString(), {
                 urls: { [_url]: source },
-            }, eventStream);
+            }, eventStream, restrictedMode !== null && restrictedMode !== void 0 ? restrictedMode : false);
         }
         for (;;) {
             const result = translator.translate(model === null || model === void 0 ? void 0 : model._modelDef);

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

@@ -5,6 +5,7 @@ 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 * as Malloy from '@malloydata/malloy-interfaces';
 import type { Taggable } from '../../taggable';
 declare abstract class Entity {
@@ -101,6 +102,7 @@ export declare class Explore extends Entity implements Taggable {
     isExploreField(): this is ExploreField;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     private parsedModelTag?;
     get modelTag(): Tag;
     /**
@@ -141,6 +143,7 @@ export declare class AtomicField extends Entity implements Taggable {
     get type(): AtomicFieldType;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     isIntrinsic(): boolean;
     isQueryField(): this is QueryField;
     isExploreField(): this is ExploreField;
@@ -208,6 +211,7 @@ export declare class QueryField extends Query implements Taggable {
     constructor(turtleDef: TurtleDef, parent: Explore, source?: Query);
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     isQueryField(): this is QueryField;
     isExploreField(): this is ExploreField;
     isAtomicField(): this is AtomicField;
@@ -223,6 +227,7 @@ export declare class ExploreField extends Explore {
     get isRecord(): boolean;
     get isArray(): boolean;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
+    get annotations(): Annotations;
     isQueryField(): this is QueryField;
     isExploreField(): this is ExploreField;
     isAtomicField(): this is AtomicField;
@@ -282,6 +287,7 @@ export declare class Model implements Taggable {
     get givens(): ReadonlyMap<string, Given>;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     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.
@@ -419,6 +425,7 @@ export declare class PersistSource implements Taggable {
      * Get annotation taglines matching an optional prefix.
      */
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     /**
      * The connection name for this source.
      */
@@ -484,6 +491,7 @@ export declare class Given implements Taggable {
     get location(): DocumentLocation | undefined;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
 }
 export declare class PreparedQuery implements Taggable {
     private _model;
@@ -494,6 +502,7 @@ export declare class PreparedQuery implements Taggable {
     get _modelDef(): ModelDef;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     /**
      * Generate the SQL for this query.
      *
@@ -537,6 +546,7 @@ export declare class PreparedResult implements Taggable {
     static fromJson({ query, modelDef, }: PreparedResultJSON): PreparedResult;
     tagParse(spec?: TagParseSpec): MalloyTagParse;
     getTaglines(prefix?: RegExp): string[];
+    get annotations(): Annotations;
     get annotation(): Annotation | undefined;
     get modelAnnotation(): Annotation | undefined;
     get modelTag(): Tag;

package/dist/api/foundation/core.js

@@ -154,8 +154,11 @@ class Explore extends Entity {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this._structDef.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this._structDef.annotation);
+    }
     get modelTag() {
-        this.parsedModelTag || (this.parsedModelTag = (0, annotation_1.annotationToTag)(this._structDef.modelAnnotation).tag);
+        this.parsedModelTag || (this.parsedModelTag = new annotation_1.Annotations(this._structDef.modelAnnotation).parseAsTag().tag);
         return this.parsedModelTag;
     }
     /**
@@ -465,6 +468,9 @@ class AtomicField extends Entity {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this.fieldTypeDef.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this.fieldTypeDef.annotation);
+    }
     isIntrinsic() {
         return (0, model_1.fieldIsIntrinsic)(this.fieldTypeDef);
     }
@@ -666,6 +672,9 @@ class QueryField extends Query {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this.turtleDef.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this.turtleDef.annotation);
+    }
     isQueryField() {
         return true;
     }
@@ -719,6 +728,9 @@ class ExploreField extends Explore {
     tagParse(spec) {
         return (0, annotation_1.annotationToTag)(this._structDef.annotation, spec);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this._structDef.annotation);
+    }
     isQueryField() {
         return false;
     }
@@ -807,6 +819,9 @@ class Model {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this.modelDef.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this.modelDef.annotation);
+    }
     /**
      * Retrieve a document reference for the token at the given position within
      * the document that produced this model.
@@ -932,7 +947,7 @@ class Model {
      */
     getBuildPlan() {
         // Require experimental.persistence compiler flag
-        const modelTag = this.tagParse({ prefix: /^##! / }).tag;
+        const modelTag = this.annotations.parseAsTag('!').tag;
         if (!modelTag.has('experimental', 'persistence')) {
             throw new Error('Model must have ##! experimental.persistence to use getBuildPlan()');
         }
@@ -1057,6 +1072,9 @@ class PersistSource {
     getTaglines(prefix) {
         return this.explore.getTaglines(prefix);
     }
+    get annotations() {
+        return this.explore.annotations;
+    }
     /**
      * The connection name for this source.
      */
@@ -1159,6 +1177,9 @@ class Given {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this._internal.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this._internal.annotation);
+    }
 }
 exports.Given = Given;
 class PreparedQuery {
@@ -1177,6 +1198,9 @@ class PreparedQuery {
     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.
      *
@@ -1281,6 +1305,9 @@ class PreparedResult {
     getTaglines(prefix) {
         return (0, annotation_1.annotationToTaglines)(this.inner.annotation, prefix);
     }
+    get annotations() {
+        return new annotation_1.Annotations(this.inner.annotation);
+    }
     get annotation() {
         return this.inner.annotation;
     }
@@ -1288,7 +1315,7 @@ class PreparedResult {
         return this.modelDef.annotation;
     }
     get modelTag() {
-        return (0, annotation_1.annotationToTag)(this.modelDef.annotation).tag;
+        return new annotation_1.Annotations(this.modelDef.annotation).parseAsTag().tag;
     }
     /**
      * @return The name of the connection this query should be run against.
@@ -1361,9 +1388,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, annotation_1.annotationToTaglines)(this.inner.annotation).map(l => ({
-            value: l,
-        }));
+        const annotations = (0, to_stable_1.toStableAnnotations)(this.inner.annotation);
         const metadataAnnot = struct.resultMetadata
             ? (0, to_stable_1.getResultStructMetadataAnnotation)(struct, struct.resultMetadata)
             : undefined;
@@ -1392,9 +1417,7 @@ class PreparedResult {
                 .set(['query_name'], this.inner.queryName || struct.name)
                 .toString(),
         });
-        const modelAnnotations = (0, annotation_1.annotationToTaglines)(this.modelDef.annotation).map(l => ({
-            value: l,
-        }));
+        const modelAnnotations = (0, to_stable_1.toStableAnnotations)(this.modelDef.annotation);
         return {
             schema,
             data,